1.2 — Comments

Types of comments

A comment is a line (or multiple lines) of text that are inserted into the source code to explain what the code is doing. In C++ there are two kinds of comments.

The // symbol begins a C++ single-line comment, which tells the compiler to ignore everything to the end of the line. For example:

1	cout << "Hello world!" << endl; // Everything from here to the right is ignored.

Typically, the single line comment is used to make a quick comment about a single line of code.

1 2 3

cout << "Hello world!" << endl; // cout and endl live in the iostream library cout << "It is very nice to meet you!" << endl; // these comments make the code hard to read cout << "Yeah!" << endl; // especially when lines are different lengths

Having comments to the right of a line can make the both the code and the comment hard to read, particularly if the line is long. Consequently, the // comment is often placed above the line it is commenting.

1 2 3 4 5 6 7 8

// cout and endl live in the iostream library cout << "Hello world!" << endl;   // this is much easier to read cout << "It is very nice to meet you!" << endl;   // don't you think so? cout << "Yeah!" << endl;

The /* and */ pair of symbols denotes a C-style multi-line comment. Everything in between the symbols is ignored.

1 2 3

/* This is a multi-line comment.    This line will be ignored.    So will this one. */

Since everything between the symbols is ignored, you will sometimes see programmers “beautify” their multiline comments:

1 2 3 4

/* This is a multi-line comment.  * the matching asterisks to the left  * can make this easier to read  */

Multi-line style comments do not nest. Consequently, the following will have unexpected results:

1 2	/* This is a multiline /* comment */ this is not inside the comment */ //                                ^ comment ends here

Rule: Never nest comments inside of other comments.

Proper use of comments

Typically, comments should be used for three things. At the library, program, or function level, comments should be used to describe whatthe library, program, or function, does. For example:

1	// This program calculate the student's final grade based on his test and homework scores.

1	// This function uses newton's method to approximate the root of a given equation.

1	// The following lines generate a random item based on rarity, level, and a weight factor.

All of these comments give the reader a good idea of what the program is trying to accomplish without having to look at the actual code. The user (possibly someone else, or you if you’re trying to reuse code you’ve already written in the future) can tell at a glance whether the code is relevant to what he or she is trying to accomplish. This is particularly important when working as part of a team, where not everybody will be familiar with all of the code.

Second, within the library, program, or function described above, comments should be used to describe how the code is going to accomplish it’s goal.

1 2 3

/* To calculate the final grade, we sum all the weighted midterm and homework scores     and then divide by the number of scores to assign a percentage.  This percentage is     used to calculate a letter grade. */

1 2 3 4 5 6

// To generate a random item, we're going to do the following: // 1) Put all of the items of the desired rarity on a list // 2) Calculate a probability for each item based on level and weight factor // 3) Choose a random number // 4) Figure out which item that random number corresponds to // 5) Return the appropriate item

These comments give the user an idea of how the code is going to accomplish it’s goal without going into too much detail.

At the statement level, comments should be used to describe whythe code is doing something. A bad statement comment explains whatthe code is doing. If you ever write code that is so complex that needs a comment to explain what a statement is doing, you probably need to rewrite your code, not comment it.

Here are some examples of bad line comments and good statement comments.

Bad comment:

1 2	// Set sight range to 0 sight = 0;

(yes, we already can see that sight is being set to 0 by looking at the statement)

Good comment:

1 2	// The player just drank a potion of blindness and can not see anything sight = 0;

(now we know WHY the player’s sight is being set to 0)

Bad comment:

1 2	// Calculate the cost of the items cost = items / 2 * storePrice;

(yes, we can see that this is a cost calculation, but why is items divided by 2?)

Good comment:

1 2	// We need to divide items by 2 here because they are bought in pairs cost = items / 2 * storePrice;

(now we know!)

Programmers often have to make a tough decision between solving a problem one way, or solving it another way. Comments are a great way to remind yourself (or tell somebody else) the reason you made a one decision instead of another.

Good comments:

1 2	// We decided to use a linked list instead of an array because // arrays do insertion too slowly.

1 2	// We're going to use newton's method to find the root of a number because // there is no deterministic way to solve these equations.

Finally, comment should be written in a way that makes sense to someone who has no idea what the code does. It is often the case that a programmer will say “It’s obvious what this does! There’s no way I’ll forget about this”. Guess what? It’s not obvious, and you will be amazed how quickly you forget. :) You (or someone else) will thank you later for writing down the what, how, and why of your code in human language. Reading individual lines of code is easy. Understanding what goal they are meant to accomplish is not.

To summarize:

• At the library, program, or function level, describe what
• Inside the library, program, or function, describe how
• At the statement level, describe why.

Commenting out code

Commenting out sections of code (temporarily) can be useful in several cases:

1) You’re working on a new piece of code that won’t compile yet, and you need to run the program. The compiler won’t let you run if there are compiler errors. Commenting out the in-progress code will allow the program to compile so you can run it.

2) You want to change the way your program executes by commenting out individual lines of code. For example, you think a particular function call is crashing your program. Commenting out the function call and running your program may indicate whether that function was the culprit.

In our upcoming examples, we will remind Visual Studio Express users that they need to start their programs with #include "stdafx.h". However, we will typically comment out this line of code, because it will cause compile errors on other compilers. Visual Studio Express users must uncomment the line before they compile.