Comments

Good comments make code easy to understand and maintain. Inappropriate comments make code more confusing than if there were no comments. The style for comments is designed to support:

Readability
Understandability
High-level code flow

This document covers:

Use C++ Comment Styles
Version Information in Comments
Comment Code Blocks
Commenting switch, if, and while Blocks
Writing Comments For Developers
Use Proper English

Use C++ Comment Styles

All comments in C++ code must use C++ comment syntax, for example:

    // This is a typical C++-type comment, using double-slashes.

The older C-style syntax using /* to begin a comment block and */ to end a block is inappropriate for final code. However, the older C-style block comment is useful during code development and debugging for temporarily commenting out code. When the code is final, all comments must conform to the C++ comment syntax.

Version Information in Comments

Comments are not a replacement for source-code control systems. In general, comments must be self-contained and refer to how the code works today, not explain its history. For this reason, comments that include specific bug fix numbers should be avoided because they don't usually make the code easier to understand.

 
    // The following comment is unnecessary! Don't force the user to look up the CCR.
    //
    // This line fixes CCR 345678.


    // This is more appropriate:
    //
    // Check for the case where the bisector touches every object on the node,
    // causing all objects on this node to move to the bisector node. CCR 123456
    // includes an example of how this can happen.

Likewise, do not comment a section of code and leave it in the file

    // Don't do this! If this code isn't being used, take it out!
    //
    // This code used to be like this
    // x = myFunc() + 10;

Neither of these examples improve the understandability of the code, and often confuse the reader.

Comment Code Blocks

In general, comments apply to blocks of code, not single lines. Most developers can look at a single line and determine what it is doing. Instead, comments should give the high-level picture.

Avoid using comments on the end of a line of code. A comment at the end of a line usually refers to something on that line. For example, do not do the following:

    oaTransform xform;

    instTbl.getOffset(xform.offset());  // Get the instance's offset.
    instTbl.getOrient(xform.orient());  // Get the instance's orientation.
    xform.mag() = instTbl.getMag();     // Get the magnification.

Instead of using an inline comment, insert a comment for the entire block of code. For example:

    // Get the instance's transform and put it in 'xform'.
    oaTransform xform;

    instTbl.getOffset(xform.offset());
    instTbl.getOrient(xform.orient());
    xform.mag() = instTbl.getMag();

Commenting switch, if, and while Blocks

The rules for commenting switch, if, and while blocks are specific to ensure readable code and improve a developer's understanding of the code functionality. It is particularly important to comment these programming constructs as blocks rather than inline and to match the indentation of comments with the block of code that they document. The following examples illustrate the correct format.

Commenting a switch Block

    // This is an example of a properly commented switch statement. Note that you
    // start the comment at the top and generically describe the purpose of the
    // entire switch().
    switch (<someTest>) {
    case one:
        // Describe a simple case here.
        <code>
        break; 

    case two: 
        // Describe here a more complicated case that requires braces.
        {
             oaUInt4      someVar;

             <code>

        }
        break;
	  
    case three: 
        // Describe another simple case here.
        <code>
        break;
	  
    default:
        // Describe the default case here.
        <code>
        break;
    }

Commenting an if Block

    // If <someCondition> is true, do <whatever>, otherwise do <somethingElse>. This
    // is where you generically describe what a complicated if/else block
    // is handling.
    if (<someCondition>) {
        // When this is complicated, it is appropriate to add additional
        // comments here to describe exactly what is happening if <someCondition>
        // is true.
        <code>
    } else {
        // It is appropriate to further describe the else clause
        // here.
        <somethingElse>
    }

Commenting a while Block

    // While <someCondition> is true, do <whatever>.
    while (<someCondition>) {
        <code>
    }
 

    // While <someCondition> is true, do <whatever>. This comment style
    //  is appropriate when the content of the loop is complicated.
    while (<someCondition>) {
        // Here is what the first sub-block does.
        <code>

        // Here is what the second sub-block does.
        <whatever>
 
        // Continue with additional comments as necessary.
        <code>
    }

Writing Comments For Developers

The audience for comments is assumed to be fluent in the programming language. Do not include comments that describe information readily apparent by looking at the code. The following comments are unnecessary:

    // While index is less than 10:
    while (index < 10) {
        .
        .
        .
    }


    if (abc != TRUE) {
        .
        .
        .
    }  // if (abc != TRUE)


    // Abort if myFunction returns false.
    if (!myFunction()) {
        return;
    }

Use Proper English

All comments must be complete sentences, grammatically correct, and free of spelling errors. Further, they must be free of slang, vernacular, and obscure references. The following comments are inappropriate:

    // Make sure our hero really wants to quit.

    // don't crash if NULL

    // You know why this code is required.

Return to top of page