 |
Defining Programming Standards |
|
|
|
CHAPTER 4 : Commenting
4.3 Header commentsA 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 commentA 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).
/*************************************************************
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 headingsSections 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:
/* -------------------------------------------------------------------------> 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:
/*
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:
/*
4.3.3 Use available tools to helpIf 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:
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******************************************************
4.3.4 Use an appropriate amount of informationA 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.
|
|
|
|
|
||||
