Professional C__ - Marc Gregoire [65]
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 Concurrent Versions System (CVS) can even assist by filling in metadata. For example, if your comment contains the string $Id$, CVS will automatically expand the comment to include the author, filename, revision, and date.
An example of a prefix comment is shown here:
/*
* $Id: Watermelon.cpp,v 1.6 2004/03/10 12:52:33 klep Exp $
*
* 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 2011, 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 create hyperlinked documentation for the project automatically. 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
*/
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 5-1.
FIGURE 5-1
Automatically generated documentation like the file shown in Figure 5-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.
Do your best to avoid offensive or derogatory language. You never know who might look at your code some day.
Liberal use of inside jokes is generally considered okay. Check with your manager.
Reference bug numbers or feature IDs when possible.
Include your initials and the date if you think somebody might want to follow up on the comment with you in the future.
Resist the temptation to include somebody else’s initials and the date to avoid having to take responsibility for the code. This could get you fired.
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 doesn’t always 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. 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