"When the code and the comments disagree, both are probably wrong." -- Norm Schryer
Complete and accurate commentary is vitally important for any program to be maintainable. Four types of comments are common; initial, section, module (or function) and in-line (or code) commentary. Each has its own purpose, importance, and guidelines.
Always prefix file with standard copyright notice and revision history
|The file should always begin with the
standard copyright notice comment block. There should also be a revision history comment
block near the beginning of the file, describing all changes to the file.
The easiest way to setup a file for the standard comments is to use the development template files.
|Write comments as you create your code||Always write comments when you are creating the code. This is when you best know what you are doing. If you wait until later, you may forget details or may never find time.|
|Describe what is happening||Comments should describe what is happening, how it is being done, what parameters mean, which globals are used and which are modified, and any restrictions or bugs. Avoid, comments that are clear from the code, as such information rapidly gets out of date. Comments that disagree with the code are of negative value. Short comments should be what comments, such as "compute mean value", rather than how comments such as "sum of values divided by n".|
|Do not comment each line, describe blocks of code instead||C is not assembler; putting a comment at the top of a 3-10 line section telling what it does overall is often more useful than a comment on each line describing micrologic.|
|Standalone comments should be aligned with surrounding code||Comments that stand alone on one or more lines should be indented at the same level as the surrounding code.|
25 May 2009
copyright 2004 Bear Consulting Group