Commenting to Explain Usage

One reason to use comments is to explain how clients should interact with the code. Normally, a developer should be able to understand what a function does simply based on the name of the function, the type of the return value, and the name and type of its parameters. However, not everything can be expressed in code. Sometimes a function requires certain pre- or postconditions that you have to explain in a comment. Exceptions that can be thrown by a function are also something that should be explained in a comment. In my opinion, you should only add a comment if it really adds any useful information. So, it’s up to the developer to decide whether a function needs a comment or not. Experienced programmers will have no problems deciding this, but less experienced developers might not always make the right decision. That’s why some companies have a rule stating that each publicly accessible function or method in a header file should have a comment explaining what it does. Some organizations go even further and formalize these comments by explicitly listing the purpose of each method, what its arguments are, what values it returns, and possible exceptions it can throw.

A comment gives you the opportunity to state, in English, anything that you can’t state in code. For example, there’s really no way in C++ code to indicate that the saveRecord() method of a database object throws an exception if openDatabase() has not been called yet. A comment, however, can be the perfect place to note this restriction, as follows:

/*
 * This method throws a "DatabaseNotOpenedException"
 * if the openDatabase() method has not been called yet.
 */
int saveRecord(Record& record);

The C++ language forces you to specify the return type of a method, but it does not provide a way for you to say what the returned value actually represents. For example, the declaration of the saveRecord() method may indicate that it returns an int (a bad design decision discussed further in this section), but the client reading that declaration wouldn’t know what the int means. A comment explains the meaning of it:

/*
 * Returns: int
 *    An integer representing the ID of the saved record.
 * Throws:
 *    DatabaseNotOpenedException if the openDatabase() method has not
 *    been called yet.
 */
int saveRecord(Record& record);

As mentioned earlier, some companies require everything about a function to be documented in a formal way. The following is an example of how such a comment for the saveRecord() method might look like:

/*
 * saveRecord()
 * 
 * Saves the given record to the database.
 *
 * Parameters:
 *    Record& record: the record to save to the database.
 * Returns: int
 *    An integer representing the ID of the saved record.
 * Throws:
 *    DatabaseNotOpenedException if the openDatabase() method has not
 *    been called yet.
 */
int saveRecord(Record& record);

However, I don’t recommend this style of commenting. The first two lines are completely useless, since the name of the function is self-explanatory. The description of the parameter also does not add any additional information. Documenting what exactly the return type represents for this version of saveRecord() is required since it returns a generic int. However, a much better design would be to return a RecordID instead of a plain int, which removes the need to add any comments for the return type. RecordID could simply be a type alias (see Chapter 11) for int, but it conveys more information. The only comment that should remain is the exception. So, the following is my recommendation for the saveRecord() method:

/*
 * Throws:
 *    DatabaseNotOpenedException if the openDatabase() method has not
 *    been called yet.
 */
RecordID saveRecord(Record& record);

Sometimes, the parameters to, and the return type from, a function are generic and can be used to pass all kinds of information. In that case you need to clearly document exactly what type is being passed. For example, message handlers in Windows accept two parameters, LPARAM and WPARAM, and can return an LRESULT. All three can be used to pass anything you like, but you cannot change their type. By using type casting, they can, for example, be used to pass a simple integer or to pass a pointer to some object. Your documentation could look like this:

 * Parameters:
 *    WPARAM wParam: (WPARAM)(int): An integer representing...
 *    LPARAM lParam: (LPARAM)(string*): A string pointer representing...
 * Returns: (LRESULT)(Record*)
 *    nullptr in case of an error, otherwise a pointer to a Record object
 *    representing...

Commenting to Explain Complicated Code

Good comments are also important inside the actual source code. In a simple program that processes input from the user and writes a result to the console, it is probably easy to read through and understand all of the code. In the professional world, however, you will often need to write code that is algorithmically complex or too esoteric to understand simply by inspection.

Consider the code that follows. It is well written, but it may not be immediately apparent what it is doing. You might recognize the algorithm if you have seen it before, but a newcomer probably wouldn’t understand the way the code works.

void sort(int inArray[], size_t inSize)
{
    for (size_t i = 1; i < inSize; i++) {
        int element = inArray[i];
        size_t j = i - 1;
        while (j >= 0 && inArray[j] > element) {
            inArray[j+1] = inArray[j];
            j--;
        }
        inArray[j+1] = element;        
    }
}

A better approach would be to include comments that describe the algorithm that is being used, and to document (loop) invariants. Invariants are conditions that have to be true during the execution of a piece of code, for example, a loop iteration. In the modified function that follows, a thorough comment at the top explains the algorithm at a high level, and inline comments explain specific lines that may be confusing:

/*
 * Implements the "insertion sort" algorithm. The algorithm separates the 
 * array into two parts--the sorted part and the unsorted part. Each
 * element, starting at position 1, is examined. Everything earlier in the
 * array is in the sorted part, so the algorithm shifts each element over
 * until the correct position is found to insert the current element. When 
 * the algorithm finishes with the last element, the entire array is sorted.
 */
void sort(int inArray[], size_t inSize)
{
    // Start at position 1 and examine each element.
    for (size_t i = 1; i < inSize; i++) {
        // Loop invariant:
        //     All elements in the range 0 to i-1 (inclusive) are sorted.

        int element = inArray[i];
        // j marks the position in the sorted part after which element 
        // will be inserted.
        size_t j = i – 1;
        // As long as the current slot in the sorted array is higher than
        // element, shift values to the right to make room for inserting
        // (hence the name, "insertion sort") element in the right position.
        while (j >= 0 && inArray[j] > element) {
            inArray[j+1] = inArray[j];
            j--;
        }
        // At this point the current position in the sorted array
        // is *not* greater than the element, so this is its new position.
        inArray[j+1] = element;        
    }
}

The new code is certainly more verbose, but a reader unfamiliar with sorting algorithms would be much more likely to understand it with the comments included.

Commenting to Convey Meta-information

Another possible reason to use comments is to provide information at a higher level than the code itself. This meta-information provides details about the creation of the code without addressing the specifics of its behavior. For example, your organization may want to keep track of the original author of each method. You can also use meta-information to cite external documents or refer to other code.

The following example shows several instances of meta-information, including the author, the date it was created, and the specific feature it addresses. It also includes inline comments expressing metadata, such as the bug number that corresponds to a line of code and a reminder to revisit a possible problem in the code later.

/* 
 * Author:  marcg
 * Date:    110412
 * Feature: PRD version 3, Feature 5.10
 */
RecordID saveRecord(Record& record)
{
    if (!mDatabaseOpen) {
        throw DatabaseNotOpenedException();
    }
    RecordID id = getDB()->saveRecord(record);
    if (id == -1) return -1;  // Added to address bug #142 – jsmith 110428
    record.setId(id);
    // TODO: What if setId() throws an exception? – akshayr 110501
    return id;
}

A change-log could also be included at the beginning of each file. The following shows a possible example of such a change-log:

/*
 * Date     | Change
 *----------+--------------------------------------------------
 * 110413   | REQ #005: <marcg> Do not normalize values.
 * 110417   | REQ #006: <marcg> use nullptr instead of NULL.
 */

Another type of meta-information is a copyright notice. Some companies require such a copyright notice at the very beginning of every source file.

It’s easy to go overboard with comments. A good approach is to discuss which types of comments are most useful with your group and to form a policy. For example, if one member of the group uses a “TODO” comment to indicate code that still needs work, but nobody else knows about this convention, the code in need of attention could be overlooked.

Commenting Every Line

One way to avoid lack of documentation is to force yourself to overdocument by including a comment for every line. Commenting every line of code should ensure that there’s a specific reason for everything you write. In reality, such heavy commenting on a large scale is unwieldy, messy, and tedious! For example, consider the following useless comments:

int result;                   // Declare an integer to hold the result.
result = doodad.getResult();  // Get the doodad's result.
if (result % 2 ==  0) {       // If the result modulo 2 is 0 ...
   logError();                // then log an error,
} else {                      // otherwise ...
   logSuccess();              // log success.
}                             // End if/else
return result;                // Return the result

The comments in this code express each line as part of an easily readable English story. This is entirely useless if you assume that the reader has at least basic C++ skills. These comments don’t add any additional information to code. Specifically, look at this line:

if (result % 2 == 0) {        // If the result modulo 2 is 0 ...

The comment is just an English translation of the code. It doesn’t say why the programmer has used the modulo operator on the result with the value 2. The following would be a better comment:

if (result % 2 == 0) {        // If the result is even ...

The modified comment, while still fairly obvious to most programmers, gives additional information about the code. The modulo operator with 2 is used because the code needs to check if the result is even.

Despite its tendency to be verbose and superfluous, heavy commenting can be useful in cases where the code would otherwise be difficult to comprehend. The following code also comments every line, but these comments are actually helpful:

// Calculate the doodad. The start, end, and offset values come from the
// table on page 96 of the "Doodad API v1.6".
result = doodad.calculate(kStart, kEnd, kOffset);
// To determine success or failure, we need to bitwise AND the result with
// the processor-specific mask (see "Doodad API v1.6", page 201).
result &= getProcessorMask();
// Set the user field value based on the "Marigold Formula."
// (see "Doodad API v1.6", page 136)
setUserField((result + kMarigoldOffset) / MarigoldConstant + MarigoldConstant);

This code is taken out of context, but the comments give you a good idea of what each line does. Without them, the calculations involving & and the mysterious “Marigold Formula” would be difficult to decipher.

Prefix Comments

Your group may decide to begin all source files with a standard comment. This is an excellent opportunity to document important information about the program and specific file. Examples of information that you might want to document at the top of every file include the following:

• The last-modified date^*
• The original author^*
• A change-log (as described earlier)^*
• The feature ID addressed by the file
• Copyright information
• A brief description of the file/class
• Incomplete features
• Known bugs

The items marked with an asterisk are usually automatically handled by your source code control solution.

Your development environment may allow you to create a template that automatically starts new files with your prefix comment. Some source control systems such as Subversion (SVN) can even assist by filling in metadata. For example, if your comment contains the string $Id$, SVN can automatically expand the comment to include the author, filename, revision, and date.

An example of a prefix comment is shown here:

/*
 * $Id: Watermelon.cpp,123 2004/03/10 12:52:33 marcg $
 * 
 * Implements the basic functionality of a watermelon. All units are expressed
 * in terms of seeds per cubic centimeter. Watermelon theory is based on the
 * white paper "Algorithms for Watermelon Processing."
 *
 * The following code is (c) copyright 2017, FruitSoft, Inc. ALL RIGHTS RESERVED
 */

Fixed-Format Comments

Writing comments in a standard format that can be parsed by external document builders is an increasingly popular programming practice. In the Java language, programmers can write comments in a standard format that allows a tool called JavaDoc to automatically create hyperlinked documentation for the project. For C++, a free tool called Doxygen (available at www.doxygen.org) parses comments to automatically build HTML documentation, class diagrams, UNIX man pages, and other useful documents. Doxygen even recognizes and parses JavaDoc-style comments in C++ programs. The code that follows shows JavaDoc-style comments that are recognized by Doxygen:

/**
 * Implements the basic functionality of a watermelon
 * TODO: Implement updated algorithms!
 */
class Watermelon
{
    public:
        /**
         * @param initialSeeds The starting number of seeds, must be > 0.
         */
        Watermelon(int initialSeeds);

        /**
         * Computes the seed ratio, using the Marigold algorithm.
         * @param slowCalc Whether or not to use long (slow) calculations
         * @return The marigold ratio
         */
        double calcSeedRatio(bool slowCalc);
};

Doxygen recognizes the C++ syntax and special comment directives such as @param and @return to generate customizable output. An example of a Doxygen-generated HTML class reference is shown in Figure 3-1.

Note that you should still avoid writing useless comments, including when you use a tool to automatically generate documentation. Take a look at the Watermelon constructor in the previous code. Its comment omits a description and only describes the parameter. Adding a description, as in the following example, is redundant:

        /**
         * The Watermelon constructor.
         * @param initialSeeds The starting number of seeds, must be > 0.
         */
        Watermelon(int initialSeeds);

Automatically generated documentation like the file shown in Figure 3-1 can be helpful during development because it allows developers to browse through a high-level description of classes and their relationships. Your group can easily customize a tool like Doxygen to work with the style of comments that you have adopted. Ideally, your group would set up a machine that builds documentation on a daily basis.

Ad Hoc Comments

Most of the time, you use comments on an as-needed basis. Here are some guidelines for comments that appear within the body of your code:

• Avoid offensive or derogatory language. You never know who might look at your code someday.
• Liberal use of inside jokes is generally considered okay. Check with your manager.
• Before adding a comment, first consider whether you can rework the code to make the comment redundant. For example, by renaming variables, functions, and classes, by reordering steps in the code, by introducing intermediate well-named variables, and so on.
• Imagine someone else is reading your code. If there are subtleties that are not immediately obvious, then you should document those.
• Don’t put your initials in the code. Source code control solutions will track that kind of information automatically for you.
• If you are doing something with an API that isn’t immediately obvious, include a reference to the documentation of that API where it is explained.
• Remember to update your comments when you update the code. Nothing is more confusing than code that is fully documented with incorrect information.
• If you use comments to separate a function into sections, consider whether the function might be broken into multiple, smaller functions.

Self-Documenting Code

Well-written code often doesn’t need abundant commenting. The best code is written to be readable. If you find yourself adding a comment for every line, consider whether the code could be rewritten to better match what you are saying in the comments. For example, use descriptive names for your functions, parameters, variables, classes, and so on. Properly make use of const; that is, if a variable is not supposed to be modified, mark it as const. Reorder the steps in a function to make it clearer what it is doing. Introduce intermediate well-named variables to make an algorithm easier to understand. Remember that C++ is a language. Its main purpose is to tell the computer what to do, but the semantics of the language can also be used to explain its meaning to a reader.

Another way of writing self-documenting code is to break up, or decompose, your code into smaller pieces. Decomposition is covered in detail in the following section.

Counters

Early in your programming career, you probably saw code that used the variable “i” as a counter. It is customary to use i and j as counters and inner-loop counters, respectively. Be careful with nested loops, however. It’s a common mistake to refer to the “ith” element when you really mean the “jth” element. When working with 2-D data, it’s probably easier to use row and column as indices, instead of i and j. Some programmers prefer using counters outerLoopIndex and innerLoopIndex, and some even frown upon using i and j as loop counters.

Prefixes

Many programmers begin their variable names with a letter that provides some information about the variable’s type or usage. On the other hand, there are as many programmers, or even more, who disapprove of using any kind of prefix because this could make evolving code less maintainable in the future. For example, if a member variable is changed from static to non-static, you have to rename all the uses of that name. If you don’t rename them, your names continue to convey semantics, but now they are the wrong semantics.

However, you often don’t have a choice and you need to follow the guidelines of your company. The following table shows some potential prefixes.

Hungarian Notation

Hungarian Notation is a variable and data-member–naming convention that is popular with Microsoft Windows programmers. The basic idea is that instead of using single-letter prefixes such as m, you should use more verbose prefixes to indicate additional information. The following line of code shows the use of Hungarian Notation:

char* pszName; // psz means "pointer to a null-terminated string"

The term Hungarian Notation arose from the fact that its inventor, Charles Simonyi, is Hungarian. Some also say that it accurately reflects the fact that programs using Hungarian Notation end up looking as if they were written in a foreign language. For this latter reason, some programmers tend to dislike Hungarian Notation. In this book, prefixes are used, but not Hungarian Notation. Adequately named variables don’t need much additional context information besides the prefix. For example, a data member named mName says it all.

Getters and Setters

If your class contains a data member, such as mStatus, it is customary to provide access to the member via a getter called getStatus() and a setter called setStatus(). To give access to a Boolean data member, you typically use is as a prefix instead of get, for example isRunning(). The C++ language has no prescribed naming for these methods, but your organization will probably want to adopt this or a similar naming scheme.

Capitalization

There are many different ways of capitalizing names in your code. As with most elements of coding style, it is very important that your group adopts a standardized approach and that all members adopt that approach. One way to get messy code is to have some programmers naming classes in all lowercase with underscores representing spaces (priority_queue) and others using capitals with each subsequent word capitalized (PriorityQueue). Variables and data members almost always start with a lowercase letter and use either underscores (my_queue) or capitals (myQueue) to indicate word breaks. Functions and methods are traditionally capitalized in C++, but, as you’ve seen, in this book I have adopted the style of lowercase functions and methods to distinguish them from class names. A similar style of capitalizing letters is used to indicate word boundaries for class and data member names.

Namespaced Constants

Imagine that you are writing a program with a graphical user interface. The program has several menus, including File, Edit, and Help. To represent the ID of each menu, you may decide to use a constant. A perfectly reasonable name for a constant referring to the Help menu ID is kHelp.

The name kHelp will work fine until you add a Help button to the main window. You also need a constant to refer to the ID of the button, but kHelp is already taken.

A possible solution for this is to put your constants in different namespaces, which are discussed in Chapter 1. You create two namespaces: Menu and Button. Each namespace has a kHelp constant and you use them as Menu::kHelp and Button::kHelp. Another, and more recommended solution is to use enumerated types, also introduced in Chapter 1.