The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

CHAPTER 4 : Commenting

PART 2 : COMMENTING AND NAMING

CHAPTER 4 : Commenting
4.1 Commenting fundamentals
4.2 Comment types
4.3 Header comments
4.4 File Header comment
4.5 Function header comments
4.6 Block comments
4.7 Trailing comments
4.8 Commenting data
4.9 The preprocessor and comments
4.10 Summary 

<--Prev page | Next page -->

4.7 Trailing comments

Trailing comments describe the action or use of a single line of code. They are usually start (and end) on the same line as the code they are commenting.

SelectSides( Players );  /* choose partners and positions */

4.7.1 Tabbing out comments

To help separate code and comments, it is common practice to tab the start of the comment away from the code. This column should be far enough away from the code to provide separation, whilst allowing space for a reasonable comment. About half-way across the page (ie. column 40) is a fair position. The closing comment token '*/' may also be tabbed out to the right margin to 'fill justify' the comment.

SelectSides( Players );             /* choose partners and positions    */

-------------------------------------------------------------------------->

If the code crosses the comment column, then the comment may be tabbed further across the page. However, in a chunk of well-commented code, this can result in a loss in the separation of code and comments.

SelectSides( Players );             /* choose partners and positions    */
ResetGame( Players, PlayerBoard, ScoreBoard );  /* start new game       */
MakeAMove( White, PlayerBoard );    /* get valid move, move a piece     */

One approach is to move the comment start column further out to the right. This, however, reduces the amount of space available for comment text, which can force either abbreviation of the comment, or wrapping the comment to the next line.

SelectSides( Players );                         /* choose ptnrs, posns  */
ResetGame( Players, PlayerBoard, ScoreBoard );  /* start new game       */
MakeAMove( White, PlayerBoard );                /* get valid move,..    */
                                                /* ..move a piece       */

An alternative approach, which also simplifies the comment-column rule, is to always use the chosen comment column. Thus, when a code line passes through the comment column, the comment for that line of code still starts in the comment column, but on the line immediately before the code line (it could also be after - choose one method). Note that this is differentiated from a block comment in that it is right justified.

SelectSides( Players );             /* choose partners and positions   */
                                    /* start new game                  */
ResetGame( Players, PlayerBoard, Scoreboard );
MakeAMove( White, PlayerBoard );    /* get valid move, move player     */

This method has a cost in vertical space, as does squeezing the comment space when comment wraps are forced. It also breaks up the code chunk.

4.7.2 Wrapping comments

When comments are 'wrapped' to successive lines, it associates the continuation comment with the first comment if it is tabbed to at least the same column. The continuation should clearly be a comment: if this is not clear then it could lead to someone adding a line of code in the middle of the comment (which, of course, will not be compiled!):

MakeAMove( White, PlayerBoard );        /* get valid move,
ValidateLayout( PlayerBoard );             then move player */ <--WRONG!

It is thus simpler and safer to start and end trailing comments on the same line.

A continuation of a previous comment should be indicated in some manner, e.g. ellipsis ('..' , as above), indenting the continuation further, or using uppercase to start comments, and using lowercase on continuation lines:

MakeAMove( White, PlayerBoard );        /* Get valid move..          */
                                        /* ..then move player        */
ValidateLayout( PlayerBoard );          /* Check/correct layout      */

4.7.3 Commenting the end of blocks

When reading nested code, it is sometimes difficult to match the end of a block with the beginning. This is particularly true of long blocks, even though they may have matching aligned braces. A short comment after the final brace will assist this matching:

if ( WordLen > W_LEN_MAX )
{
    ...
    lots of code
    ...
} /* end if */

Note that the comment is not tabbed right, as it has a close association with the closing brace (it is separated from it by a single space).

If there are a number of nested if's, then this may still be confusing ("Which 'if' does it end?"). This can be solved by adding enough of the condition to make it identifiable.

} /* end if ( WordLen.. ) */

This method could be used on all blocks, although it might be preferable to define a 'long block' on which it is to be used (eg. > 10 lines). Some constructs have naturally long blocks - most notably switch's. It can also be used on preprocessor blocks:

#if defined( TRACE )

...

#endif /* defined( TRACE ) */

4.7.4 Comment changed lines

In a situation where changes to frozen code must be carefully controlled and a version control system is not used or does not give sufficient detail, all changed lines may be commented. A simple method is to use a unique number to identify the change:

VolumeSetting = ReadControl( CTL_VOLUME );               /* CHG:165327 */

The description for the change or even a 'commented out' copy of the old code could be put here, but it would disturb the flow of the reader who is not interested in why things have changed. This description is better put in the file header comment, and unless there are very specific reasons for leaving changed code in place it is better to use the change code to access the old code in the version control system.

4.7.5 Trailing vs. Block comments

Trailing comments are more difficult to use than block comments, as they must share line space with code. They can also intrude into code-space making the code less immediately distinguishable. In their favour, they save on vertical space and allow more precise description of a code line.

Block comments occupy more vertical space but are easily separated from the code and are thus often preferable. This, however, is not an excuse for less commenting and there should be a reasonable proportion of comment to code: typically one to three lines of comment for every chunk (around seven lines) of code.

Trailing comments should generally be used for situations where lines of code require specific clarification, such as around complex code, and to mark block ends (see 4.7.4), rather than as a standard item for most lines.

<--Prev page | Next page -->