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.3 Header comments

A consistent approach to the layout and contents of major headers, particularly those with similar purpose, makes them easier to read and understand.

4.3.1 Make clear the extent of the comment

A bar across the top emphasizes that it is commenting code below (not above). A bar down the side makes it clear at each line that this is indeed a comment (see 4.6).

/*************************************************************
*
*         Body of comment
...
*/

Putting the comment at the start of a page also dissociates it from the code above, and ensures that it will be all on one page. If it is a large header which will occupy most of the page, then rather than have a few lines of code widowed below it, then it is probably sensible to start the code on another new page. Having the comment alone on a page dissociates it from the code below, but also makes it easier to remove or copy it from the printout to make a 'manual' for the code.

4.3.2 Use section headings

Sections within the header comment can be made easier to find by using headings, although if there are very few sections, then this may not be necessary. Using capital letters for the section headings makes them more easily distinguishable and tabbing out information helps readability:

/*
...
* GLOBAL DATA:      int     DB_ErrStatus          Contains most recent
*                                                 database error

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

Note how this 'toothbrush' layout (see 6.1.4) uses up horizontal space. A 'comb' layout makes it easier to add more significant comments using less vertical space:

/*
...
* GLOBAL DATA:
*       int     DB_ErrStatus          Contains most recent database error

Where a section is empty, it may be permissible to save vertical space and remove the heading, although it is being explicit to actually say that it is empty:

/*
...
* GLOBAL DATA:       None

4.3.3 Use available tools to help

If you use a version/revision control system to control your code, then some of the information above may be extracted by using control flags.

* RCS LOG:
*       $LOG$

If you bracket the header with '/*H' and 'H*/', you can create an 'automatic documentation tool' to extract file headers. The same idea can be applied to other comments that may usefully be extracted, using a different letter for different header types:

/*H******************************************************
*
...  This header comment can be automatically extracted
*
*H*/

4.3.4 Use an appropriate amount of information

A large and complex function which is essential for the reader to understand will probably require a large and detailed function header comment. However, to require that the same template be used for a simple 5 line function is overkill (and probably would not get used).

It is a good idea to identify different levels of header (e.g. subsystem interface functions, file public functions and file private functions), and specify required and optional sections for each level.

Beware of this principle being used to interpret 'appropriate amount' as 'what I feel like giving'. The acid test is, as ever, what will be helpful to all of the future readers of the code.

<--Prev page | Next page -->