When you are writing a program, it is always clear and self-evident what you are trying to do. Funny thing, though—a month later, when you return to the program, it can be quite confusing and unclear. I’m not sure how that confusion creeps into your program, but it always does.

To fight the onset of confusion, and to help others understand your code, you’ll want to use comments. Comments are simply text that is ignored by the compiler, but that may inform the reader of what you are doing at any particular point in your program.

C++ comments come in two flavors: the double-slash (//) comment, and the slash-star (/*) comment. The double-slash comment, which will be referred to as a C++-style comment, tells the compiler to ignore everything that follows this comment, until the end of the line.

The slash-star comment mark tells the compiler to ignore everything that follows until it finds a star-slash (*/) comment mark. These marks will be referred to as C-style comments. Every /* must be matched with a closing */.

As you might guess, C-style comments are used in the C language as well, but C++-style comments are not part of the official definition of C.

Many C++ programmers use the C++-style comment most of the time, and reserve C-style comments for blocking out large blocks of a program. You can include C++-style comments within a block "commented out" by C-style comments; everything, including the C++-style comments, is ignored between the C-style comment marks.

As a general rule, the overall program should have comments at the beginning, telling you what the program does. Each function should also have comments explaining what the function does and what values it returns. Finally, any statement in your program that is obscure or less than obvious should be commented as well.

Listing 2.3 demonstrates the use of comments, showing that they do not affect the processing of the program or its output.

Listing 2.3. HELP.CPP demonstrates comments.

1: #include <iostream.h>

2:

3: int main()

4: {

5: /* this is a comment

6: and it extends until the closing

7: star-slash comment mark */

8: cout << "Hello World!\n";

9: // this comment ends at the end of the line

10: cout << "That comment ended!\n";

11:

12: // double slash comments can be alone on a line

13: /* as can slash-star comments */

14: return 0;

15: }

OUTPUT :

Hello World!

That comment ended!

The comments on lines 5 through 7 are completely ignored by the compiler, as are the comments on lines 9, 12, and 13. The comment on line 9 ended with the end of the line, however, while the comments on lines 5 and 13 required a closing comment mark.

Comments at the Top of Each File

It is a good idea to put a comment block at the top of every file you write. The exact style of this block of comments is a matter of individual taste, but every such header should include at least the following information:

· The name of the function or program.

· The name of the file.

· What the function or program does.

· A description of how the program works.

· The author’s name.

· A revision history (notes on each change made).

· What compilers, linkers, and other tools were used to make the program.

· Additional notes as needed.

For example, the following block of comments might appear at the top of the Hello World program.

/************************************************************

Program: Hello World

File: Hello.cpp

Function: Main (complete program listing in this file)

Description: Prints the words "Hello world" to the screen

Author: Jesse Liberty (jl)

Environment: Turbo C++ version 4, 486/66 32mb RAM, Windows 3.1

DOS 6.0. EasyWin module.

Notes: This is an introductory, sample program.

Revisions: 1.00 10/1/94 (jl) First release

1.01 10/2/94 (jl) Capitalized "World"

************************************************************/

It is very important that you keep the notes and descriptions up-to-date. A common problem with headers like this is that they are neglected after their initial creation, and over time they become increasingly misleading. When properly maintained, however, they can be an invaluable guide to the overall program.

The listings in the rest of this book will leave off the headings in an attempt to save room. That does not diminish their importance, however, so they will appear in the programs provided at the end of each week.

A Final Word of Caution About Comments

Comments that state the obvious are less than useful. In fact, they can be counterproductive, because the code may change and the programmer may neglect to update the comment. What is obvious to one person may be obscure to another, however, so judgment is required.

The bottom line is that comments should not say what is happening, they should say why it is happening.

DO add comments to your code. DO keep comments up-to-date. DO use comments to tell what a section of code does. DON’T use comments for self-explanatory code.