The Syntax of Visual C++ Comments

Begin all comments with two slashes, //. 

---

In computer lingo, language syntax refers to the spelling of commands, the ordering of special characters, and the placing of the language elements. When you learn the syntax for a Visual C++ command or operation, you learn the exact format required so that Visual C++ knows what you want it to do. 

Comments are so important that you are now going to learn the syntax of comments (how to write comments so that Visual C++ knows that they are comments) before you learn any Visual C++ commands. Use comments abundantly so that someone reading your program later has a clear guide to the program's contents. A Visual C++ programmer might be able to trace through your Visual C++ code and figure out what the program does, but comments speed the process. The faster someone understands your code, the faster he or she can make any needed changes and move on to other projects. 

A comment begins with two forward slashes, sometimes called a double slash. Comments extend to the end of the line. In other words, you cannot have a command, a comment, and then another command all on the same line. Here is an example of a Visual C++ line with a comment: 

return ((a > b)?a:b);  // Grabs the larger of two values

Here is the same line without the comment: 

return ((a > b)?a:b);

With a comment, you don't even have to know Visual C++ in order to know what the statement is doing. Without a comment, as you can see, the statement looks like garbage characters that make no sense. 

The double slash is vital: without it, Visual C++ would refuse to accept the line. Even though return ((a > b)?a:b); is a valid Visual C++ command, if you left out the double slash comment signal, Visual C++ would see the words Grabs the larger of two values and not know what to do with them. After all, Visual C++ does not know English; it knows only C++. The comment is there not for Visual C++ but for a person looking through your program. 

Comments can reside on lines all by themselves. Sometimes you use comments for more than one program statement. Comments are useful for describing a section of several lines in a program and for putting in program notes about the programmer and the program. For example, the following small Visual C++ program contains two lines of comments that extend the entire line length, as well as three additional comments to the right of Visual C++ code. 

// Filename: COMAVGE.CPP  // Program to compute the average of three values  #include   void main()    {      float g1, g2, g3;   // Variables to hold student grades      cout << "What grade did the first student get? ";      cin >> g1;      cout << "What grade did the second student get? ";      cin >> g2;      cout << "What grade did the third student get? ";      cin >> g3;      float avg = (g1 + g2 + g3) / 3.0;   // Computes average      cout << "The student average is " <<>

All of the programs on this book's program disk are stored under a separate filename. You must tell your Visual C++ compiler the program's filename before it can load the program into memory and run it. To help you quickly try the examples throughout this book, a comment on the first line of every program contains the name of the program as it is stored on the disk. For instance, you can load the preceding program from the book's program disk by retrieving the file named COMAVGE.CPP. 

Many companies require their programmers to put their names in comments at the top of programs they write. If someone later has a question about the program, the original programmer can be traced. If several people make changes to a program, they often put their names too, with a brief comment about the changes they made. Because all these types of lines are commented, Visual C++ skips over them, as it should. Often, they also put a brief description of what the program is supposed to do at the beginning. 

Scatter comments throughout a program as well. If you write some tricky code that needs explanation, spend a few lines of comments, if needed, explaining what the next few lines of code do. 

---

Be proud of yourself! You do not yet know one bit of Visual C++ code, yet you understand exactly what the preceding program does. That's the purpose of comments! They document a program so that you don't have to go through tedious code to learn what parts of the program are doing. 

---

A Visual C++ programmer usually can understand what a simple Visual C++ program is supposed to do, even if the program has no comments at all. As soon as you learn the Visual C++ language, you will be able to look through straight Visual C++ code, with no comments, and make changes that need to be made. The comments simply help describe what the program is doing. 

---

Comments begin with // and extend to the end of the line. You can put comments on lines by themselves or at the end of other C++ code. 

---

Comments Are For You, Too

---

Even if you write programs that you will maintain yourself, you'll need comments. 

---

Suppose that you write programs for your own use and amusement. Nobody but you will ever see the Visual C++ code you write. Can you think of why you should take the time to add comments to your own programs? There are plenty of reasons. 

Suppose that you write a Visual C++ program to track your bank records. A year later, your bank allows for automatic transfers of utility bill payments straight from your savings account. Your old program no longer suffices for the new banking system, so you get the Visual C++ code out and begin making changes. However, you can't remember what you did before, and the code is so succinct that it is difficult to follow. Luckily, you put comments in the code, so you read through the program until you get to the place you need to change. As soon as you are there, you know what is going on in the code, and you quickly make the changes. 

Get into the habit of commenting as you write programs. Many people write programs without commenting as they go, thinking that they will add comments later. More often than not, the comments never get added. When program maintenance is required, it takes twice as long to change the code as it would if the programmer had added comments during the original programming phase. 

As important as comments are, you can over-comment a program. Add comments to lines only when the program's code warrants it. You see many more comments in the first few programs in this book than you see later. As you learn the simple commands, this book attempts to clarify them through extra comments in the program listings. 

Nevertheless, redundant comments are as bad as no comments at all. For example, even though you know nothing about Visual C++ commands, you might agree that the following code contains worthless comments: 

totalsales = oldsales + newsales;   // Adds the old sales and                                      // the new sales to get                                      // total sales  cout << "Happy Birthday";   // Sends the Happy Birthday                              // message to the cout  return;   // Return

Each of these comments is redundant, and they really do not explain what is going on any more than the Visual C++ code itself. However, consider this statement: 

for (int ctr = 10; ctr > 0; ctr) // Prints the numbers    {                              // from 10 to 1      cout <<>

Although you don't know Visual C++ (and even if you did), you can see that the purpose of these two lines of code is hidden in the cryptic Visual C++ language. A Visual C++ programmer could figure out this code, but the comment makes it effortless. As you saw in the previous three code fragments, comments often span more than one line. Continue a comment on the next line (remembering to use a double slash) if it is too long to place on a single line. 

It is also useful to describe in your comments why your program is doing something. In the previous snippet, it would be obvious to a C++ programmer that the program was putting the numbers on the screen. If this was part of a graph drawing program, it might be more helpful to comment it like this: 

//  //  Display the range of the graph on the screen  //  for (int ctr = 10; ctr > 0; ctr)     {      cout <<>

Now you understand why the program has a piece of code in it. 

---

After writing a program, you'll need comments even if you maintain the program yourself. Use comments only when they help explain what is going on in the code. 

---

C-Style Comments

---

Visual C++ supports your use of the old C-style comments that begin with /* and end with */. 

---

Visual C++ supports another kind of comment that you might see occasionally. Visual C++ is based on the C language, but Visual C++'s comment syntax differs from C's. The designers of Visual C++ decided to keep the old C-style comment syntax so that C programs would work, with little or no change, with Visual C++ compilers. Nevertheless, the double slash comments are considered superior. You should learn C comments just in case you see them. 

A comment in C begins with the characters /* and ends with the characters */. Unlike with Visual C++ comments, you must end a C comment. If you do not put the ending */, C assumes that the next line (or the next hundred lines) is still a comment until it finally finds another */. The following line contains a C-style comment: 

char name[25];   /* Reserves space for a 25-character name */

Because a C comment ends only when the */ is reached, the following three lines make up a single comment: 

/* The following program calculates stock statistics  using the most modern technical analysis techniques  available. */

Of course, the three lines could also be commented like this: 

/* The following program calculates stock statistics */  /* using the most modern technical analysis techniques */  /* available. */

Although you should become familiar with C comments, true Visual C++ programmers tend to avoid using them. The double slash is easier because you don't have to remember to end the comment. The C-style comments can be error-prone as well. If you embed one C-style comment within another, Visual C++ gets confused. Stay with Visual C++ comments as much as possible, and both you and your Visual C++ compiler will lead healthier and more productive lives. 

---

C comments can be dangerous if you accidentally embed one within another. Stick to C++'s // comment style. There might be times, however, when you run across C comments in a C++ program and you should understand their format.