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.

Types of
Comments

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.

Using Comments

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 below demonstrates the use of comments, showing that they do not
affect the processing of the program or its output.

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.

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.