3.1 Comments

Ideally, a program serves two purposes: First, it presents the computer with a set of instructions, and second, it provides the programmer with a clear, easy-to-read description of what the program does.

Example 2-1 contains a glaring error. It is an error that many programmers still make and one that causes more trouble than any other problem. The program contains no comments.

A working but uncommented program is a time bomb waiting to explode. Sooner or later someone will have to modify or upgrade the program, and the lack of comments will make the job ten times more difficult. A well-commented, simple program is a work of art. Learning how to comment is as important as learning how to code properly.

C++ has two flavors of comments. The first type starts with /* and ends with */. This type of comment can span multiple lines as shown:

/* This is a single-line comment. */
/* 
 * This is a multiline comment.
 */

The other form of comment begins with // and goes to the end of the line:

// This is another form of comment.
// The // must begin each line that is to be a comment.

The advantage of the /* */ comment style is that you can easily span multiple lines, whereas with the // style you have to keep putting the // on each line. The disadvantage of /* */ is that forgetting a */ can really screw up your code. (Remember this because it's the answer to one of the questions later in the book.)

Which flavor should you use? Whichever one makes your program as clear and as easy to read as possible. Mostly, it's a matter of taste. In this book we use the /* */ style comments for big, multiline comments, and the // style is reserved for comments that take up only a single line.

Whatever comment style you decide to use, you must comment your programs. Example 3-1 shows how the "hello world" program looks after comments are added.

Example 3-1. hello2/hello2.cpp

/********************************************************
 * hello -- program to print out "Hello World".         *
 *      Not an especially earth-shattering program.     *
 *                                                      *
 * Author: Steve Oualline                               *
 *                                                      *
 * Purpose: Demonstration of a simple program           *
 *                                                      *
 * Usage:                                               *
 *      Run the program and the message appears         *
 ********************************************************/
#include <iostream>

int main(  )
{
    // Tell the world hello
    std::cout << "Hello World\n";
    return (0);
}

In this program, the beginning comments are in a box of asterisks (*) called a comment box. This is done to emphasize the more important comments, much like bold characters are used for the headings in this book. Less important comments are not boxed. For example:

    // Tell the world hello
    std::cout << "Hello World\n"; 

Poor Person's Typesetting In typesetting you can use font style and size, bold, and italic to make different parts of your text stand out. In programming, you are limited to a single, monospaced font. However, people have come up with ingenious ways to get around the limitations of the typeface. Here are some of the various commenting tricks: /******************************************************** ******************************************************** ******** WARNING: This is an example of a ******* ******** warning message that grabs the ******* ******** attention of the programmer. ******* ******************************************************** ********************************************************/ //------------> Another, less important warning <-------- //>>>>>>>>>>>> Major section header <<<<<<<<<<<<<<<< /******************************************************** * We use boxed comments in this book to denote the * * beginning of a section or program * ********************************************************/ /*------------------------------------------------------*\ * This is another way of drawing boxes * \*------------------------------------------------------*/ /* * This is the beginning of a section * ^^^^ ^^ ^^^ ^^^^^^^^^ ^^ ^ ^^^^^^^ * * In the paragraph that follows we explain what * the section does and how it works. */ /* * A medium-level comment explaining the next * dozen or so lines of code. Even though we don't have * the bold typeface we can **emphasize** words. */ // A simple comment explaining the next line

To write a program, you must have a clear idea of what you are going to do. One of the best ways to organize your thoughts is to write them down in a language that is clear and easy to understand. Once the process has been clearly stated, it can be translated into a computer program.

Understanding what you are doing is the most important part of programming. I once wrote two pages of comments describing a complex graphics algorithm. The comments were revised twice before I even started coding. The actual instructions took only half a page. Because I had organized my thoughts well (and was lucky), the program worked the first time.

Your program should read like an essay. It should be as clear and easy to understand as possible. Good programming style comes from experience and practice. The style described in the following pages is the result of many years of programming experience. It can be used as a starting point for developing your own style. These are not rules, but only suggestions. The only rule is this: Make your program as clear, concise, and simple as possible.

At the beginning of the program is a comment block that contains information about the program. Boxing the comments makes them stand out. The list that follows contains some of the sections that should be included at the beginning of your program. Not all programs will need all sections, so use only those that apply.

Heading

The first comment should contain the name of the program. Also include a short description of what it does. You may have the most amazing program, one that slices, dices, and solves all the world's problems, but it is useless if no one knows what it does.

Author

You've gone to a lot of trouble to create this program. Take credit for it. Also, if someone else must later modify the program, he or she can come to you for information and help.

Purpose

Why did you write this program? What does it do?

Usage

In this section, give a short explanation of how to run the program. In an ideal world, every program comes with a set of documents describing how to use it. The world is not ideal. Oualline's law of documentation states that 90% of the time the documentation is lost. Out of the remaining 10%, 9% of the time the revision of the documentation is different from the revision of the program and therefore completely useless. The 1% of the time you actually have the correct revision of the documentation, the documentation will be written in a foreign language.

To avoid falling prey to Oualline's law of documentation, put the documentation in the program.

References

Creative copying is a legitimate form of programming (if you don't break the copyright laws in the process). In the real world, it doesn't matter how you get a working program, as long as you get it, but give credit where credit is due. In this section you should reference the original author of any work you copied.

File formats

List the files that your program reads or writes and a short description of their format.

Restrictions

List any limits or restrictions that apply to the program, for example, the data file must be correctly formatted or the program does not check for input errors.

Revision history

This section contains a list indicating who modified the program and when and what changes have been made. Many computers have a source control system (RCS, CVS, and SCCS on Unix; MKS-RCS and PCVS on Microsoft Windows) that will keep track of this information for you.

Error handling

If the program detects an error, what does it do with it?

Copyright and license

Some companies require that you include a copyright notice (for example, "Copyright 2002, BB Software Corp.").

On the other hand, many open source programs include a copyright and license. The most popular open source license is the GNU Public License (GPL). (For more information see http://www.gnu.org.)

Notes

Include special comments or other information that has not already been covered.

The format of your beginning comments will depend on what is needed for the environment in which you are programming. For example, if you are a student, the instructor may ask you to include in the program heading the assignment number, your name, student identification number, and other information. In industry, a project number or part number might be included.

Comments should explain everything the programmer needs to know about the program, but no more. It is possible to overcomment a program. (This is rare, but it does happen.) When deciding on the format for your heading comments, make sure there is a reason for everything you include.

Inserting Comments—The Easy Way If you are using the Unix editor vi, put the following in your .exrc file to make it easier to construct boxes. :abbr #b /************************************************ :abbr #e ************************************************/ These two lines define vi abbreviations #b and #e, so that typing #b and pressing RETURN at the beginning of a block will cause the string: /************************************************ to appear (for beginning a comment box). Typing #e and hitting RETURN will end a box. The number of stars was carefully selected to align the end of the box on a tab stop.