Comments are intended to aid in the understanding of the code. You may assume
that the person reading the comments knows the C language about as well as
you do; however, you may not assume that reader understands anything
about the particular problem that your code is trying to solve. This leads to
the general rule, "comment the purpose of the code, not the implementation"
[Lapin 1987].
Extraneous comments about obvious features of C
(e.g., /* increment i */
) will cause
the reader of your code to "tune out" the comments altogether.
There are three distinct styles of comments used in IPW source code:
Examples:
#define ERROR (-1) /* description of "ERROR" */ int foo( int bar) /* description of "bar " */ { ... C code ... /* * a block comment describing the purpose * (as opposed to the implementation) * of the next several lines */ ... C code ... /* a one-line comment about the next statement */ ... C code ... }
The top-level unit of documentation is a globally-scoped (i.e., defined outside any block) function or variable. Each module (compiled source file) should contain exactly one global object. Preserving a one-to-one correspondence between modules and linkable objects minimizes the amount of unused code that gets linked into an executable program.
Procedural code should be thought of as consisting of "paragraphs" of C statements. The purpose of each paragraph of statements should be described in a preceding block comment. Block comments should be terse, and should amplify, NOT simply re-state, the following code. In particular, comments should not contain pseudo-code: the actual code should be as readable as any pseudo-code description.
If a paragraph of code implements a published algorithm, then the preceding block comment should contain a full reference to the publication, including page and equation numbers.
One-line comments should not be used where a block comment would achieve the same purpose, since the change in comment styles is inherently distracting. Instead, one-line comments should be used chiefly to call attention to "gray areas" in the code, which might require maintenance. For example, a potentially non-portable use of C could be flagged with a one-line comment.
Variable definitions always contain an end-of-line comment. If the permissible values of the variable are restricted to a subrange of its type, then the subrange should be specified in the comment. Similarly, any physical units associated with values of the variable (meters, degrees, etc.) should be documented in the end-of-line comment, unless they are obvious from the variable name.