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 yo...
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 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: }
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.
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.
