As you are writing your own programs for the first time, it will seem perfectly clear to you what each line of the source code does. But as time passes and you come back to the program to fix a bug or add a new feature, you may find yourself completely mystified by your own work.
To avoid this predicament and help others understand your program, you can document your source code with comments. Comments are lines of text that explain what a program is doing. The compiler ignores them, so they are strictly for benefit of humans reading the code.
There are two types of comments in C++. A single-line comment begins with two slash marks (//) and causes the compiler to ignore everything that follows the slashes on the same line. Here’s an example:
// The next line is a kludge (ugh!)
A multiple-line comment begins with the slash and asterisk characters (/*) and ends with the same characters reversed (*/). Everything within the opening /* and the closing */ is a comment, even if it stretches over multiple lines. If a program contains a /* that is not followed by a */ somewhere, that’s an error likely to be flagged by the compiler. Here’s a multiline comment:
/* This part of the program doesn't work very well. Please remember to fix this before the code goes live –– or else find a scapegoat you can blame for the problem. The new guy Curtis would be a good choice. */
In the preceding comment, the text on the left margin is lined up to make it more readable. This is not required. Because the compiler ignores everything within the /* and */, anything can be put there—grocery lists, love poems, secrets you’ve never told anybody in your life, and so on.
The next project that you create includes both kinds of comments. Write lots of comments in your programs. The more time spent writing comments that explain what’s going on in source code, the easier that code will be to work on weeks, months or even years later.