- A Simple Program
- A Brief Look at cout
- Using the Standard Namespace
- Commenting Your Programs
- Functions
- Summary
- Q&A
- Workshop
This chapter is from the book
This chapter is from the book
This chapter is from the book
Commenting Your Programs
When you are writing a program, your intent is always clear and self-evident to you. Funny thing, though—a month later, when you return to the program, it can be quite confusing and unclear. No one is ever certain how the confusion creeps into a program, but it nearly always does.
To fight the onset of bafflement, and to help others understand your code, you need to use comments. Comments are text that is ignored by the compiler, but that can inform the reader of what you are doing at any particular point in your program.
Types of Comments
C++ comments come in two flavors: single-line comments and multiline comments. Single-line comments are accomplished using a double slash (//). The double slash tells the compiler to ignore everything that follows, until the end of the line.
Multiline comments are started by using a forward slash followed by an asterisk (/*). This “slash-star” comment mark tells the compiler to ignore everything that follows until it finds a “star-slash” (*/) comment mark. These marks can be on the same line or they can have one or more lines between them; however, every /* must be matched with a closing */.
Many C++ programmers use the double-slash, single-line comments most of the time and reserve multiline comments for blocking out large blocks of a program. You can include single-line comments within a block commented out by the multiline comment marks; everything, including the double-slash comments, is ignored between the multiline comment marks.
Using Comments
Some people recommend writing comments at the top of each function, explaining what the function does and what values it returns. Functions should be named so that little ambiguity exists about what they do, and confusing and obscure bits of code should be redesigned and rewritten so as to be self-evident. Comments should not be used as an excuse for obscurity in your code.
This is not to suggest that comments ought never be used, only that they should not be relied upon to clarify obscure code; instead, fix the code. In short, you should write your code well, and use comments to supplement understanding. Listing 2.5 demonstrates the use of comments, showing that they do not affect the processing of the program or its output.
Listing 2.5. Demonstrates Comments
1: #include <iostream>
2:
3: int main()
4: {
5: using std::cout;
6:
7: /* this is a comment
8: and it extends until the closing
9: star-slash comment mark */
10: cout << "Hello World!\n";
11: // this comment ends at the end of the line
12: cout << "That comment ended!\n";
13:
14: // double-slash comments can be alone on a line
15: /* as can slash-star comments */
16: return 0;
17: }
Output
Hello World! That comment ended!
Analysis
The comment on lines 7–9 is completely ignored by the compiler, as are the comments on lines 11, 14, and 15. The comment on line 11 ended with the end of the line. The comments on lines 7 and 15 required a closing comment mark.
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 might change and the programmer might neglect to update the comment. What is obvious to one person might be obscure to another, however, so judgment is required when adding comments. The bottom line is that comments should not say what is happening, they should say why it is happening.