Barr Group FacebookBarr Group TwitterBarr Group LinkedInBarr Group Vimeo

Rules

The following C coding rules relate to the placement and internal structure of comments:

Rule 2.2.a.) All comments shall be written in clear and complete sentences, with proper spelling and grammar and appropriate punctuation.

Rule 2.2.b.) The most useful comments generally precede a block of code that performs one step of a larger algorithm. (Note: It is a good practice to write the comment blocks first, as you should not begin the coding until you can explain the logic, algorithm, or sequence of steps in words.) A blank line shall follow each such code block. The comments in front of the block should be at the same indentation level.

Rule 2.2.c.) Avoid explaining the obvious. Assume the reader knows the C programming language. For example, end-of-line comments should only be used in exceptional circumstances, where the meaning of that one line of code may be unclear from the variable and function names and operations alone but where a short comment makes it clear. Avoid writing unhelpful and redundant comments such as “shift left 2 bits”.

Rule 2.2.d.) The number and length of individual comment blocks shall be proportional to the complexity of the code they describe.

Rule 2.2.e.) Whenever an algorithm or technical detail has come from a published source, the comment shall include a sufficient reference to the original source (via book title, website URL, or other details) to allow a reader of the code to find the cited reference material.

Rule 2.2.f.) Whenever a flow-chart or other diagram is needed to sufficiently document the code, the drawing shall be maintained with the source code under version control and the comments should reference the diagram by file name or title.

Rule 2.2.g.) All assumptions shall be spelled out in comments. (Note: Of course, a set of design-by-contract tests or assertions is even better than comments.)

Rule 2.2.h.) h. Each module and function shall be commented in a manner suitable for automatic documentation generation via Doxygen (http://www.doxygen.org).

Rule 2.2.i.) Use the following capitalized comment markers to highlight important issues:

  1. WARNING: alerts a maintainer there is risk in changing this code. For example, that a delay loop counter’s terminal value was determined empirically and may need to change when the code is ported or the optimization level tweaked.
  2. NOTE: provides descriptive comments about the “why” of a chunk of code—as distinguished from the “how” usually placed in comments. For example, that a chunk of driver code deviates from the datasheet because there was an errata in the chip. Or that an assumption is being made by the original programmer.
  3. TODO: indicates an area of the code is still under construction and explains what remains to be done. When appropriate, an all-caps programmer name or set of initials may be included before the TODO:.

Example

// Step 1: Batten down the hatches.
for (int hatch = 0; hatch < NUM_HATCHES; hatch++)
{
    if (hatch_is_open(hatches[hatch])
    {
        hatch_close(hatches[hatch]);
    }
}

// Step 2: Raise the mizzenmast.
// TODO: Define mizzenmast driver API. 

Reasoning

Following these rules results in good comments. And good comments result in good code. Unfortunately, it is easy for source code and documentation to drift over time. The best way to prevent this is to keep the documentation as close to the code as possible. Doxygen is a useful tool to regenerate documentation describing the modules, functions, and parameters of a project as that code is changed.

Exceptions

Individual projects may standardize the use of Doxygen features of beyond those in the template files.

Enforcement

The quality of comments shall be evaluated during code reviews. Code reviewers should be on the lookout both that the comments accurately describe the code and that they are clear, concise, and valuable. Rebuilds of Doxygen-generated documentation files, for example in HTML or PDF, shall be automated and made part of the software build process.

Comments:

Rule 2.2.b suggests explanatory block comments. Why not just improve the code by extracting the block into a function named batten_down_the_hatches();

Save comments for things that code cannot be expressed by the code itself.

Here are some suggestions for commenting from the blog Agile in a Flash: http://agileinaflash.blogspot.com/2009/04/rules-for-commenting.html

What’s happening and how it’s done. Get in the know.

Sign up for our newsletter today!

Receive free how-to articles, industry news, and the latest info on Barr Group webinars and training courses via email. 

To prevent automated spam submissions leave this field empty.