6.2 Comments

Commenting has always been a delicate matter, requiring taste and judgment. One should assume that others reading the code know the implementation language. Code that is clear, using good type and variable names, should be self-explanatory - at a micro level. Comments should explain the less-than-obvious aspects of the code, at a macro level.

Note: The comments need to explain why things were done and the big picture of how something works and the ways in which the various pieces relate to each other.

By definition, misleading comments can cause confusion. When you modify code, you should always check the comments to ensure that they accurately document the modified code. Comments are not checked by the compiler, and are therefore not guaranteed to be correct. Comments are even more of a risk following code modification.

Write your comments assuming that they are going to be read by someone with minimal familiarity with the code. Clarity is important, but one should also strive for terse and concise comments. One should be able to see both the comment, and the code being commented on, on the same screen.

6.2.1 Only use C style, "/*", comments for multi-line comments and on the same line as pre-processor directives.

Compile can vary in their support for use of // in preprocessor directives (e.g. #define). Note that the mixing of /* ... */ and // is not handled consistently. This goes beyond style issues; various (pre C99) compilers may not behave the same.

6.2.2 Avoid banners or other decoration around blocks of comments.

Banners can be useful to highlight logical divisions within a file; such as before vital sections. This type of usage should be minimized.

6.2.3 Avoid comments where the opening comment characters are alone on a line.

/*
 * VIOLATION: Horror Vacui
*/

or

//
// VIOLATION: Horror Vacui
//

6.2.4 Do not include jokes or obtuse references in comments.

"Out of cheese error! Redo from start."