|
|
|
|
|
by kazinator
4314 days ago
|
|
Comments which reveal the intent of a block of code are very useful. They provide useful clues precisely when the code does not meet the expressed intent: /* Dear Maintainer,
* I write the following in the sincere hope that
* it sorts the variables a, b and c in ascending order.
*/
if (a > b) swap(a, b);
if (b > c) swap(b, c);
They are useful when the code is complicated and the intent is not obvious. Or when there can be multiple plausible intents based on what the requirements are. Sometimes code contains implementations of requirements that are not spelled out in any requirements document. A high level requirement can break down into lower-level ones in umpteen ways. Whatever isn't in the detailed design document is only in the comments and the code. A programmer's statement of intent can in fact be a requirement specification: the only such document for that piece of code. |
|