Lesson 12	Comment style
Objective	Examine the preferred comment style in C++.

C++ Preferred Comment Style

Programs must be documented to be useful. C++ introduces a rest-of-line comment symbol //. This one-line comment symbol is an addition to, rather than a replacement of, the bracket-pair multi-line comment symbols /* */ of C.
Everything on a single line after the symbol // is treated as a comment. This is not the case when the symbol is part of a character or string.
CPlus Comment Style
The rest-of-line comment symbol is the preferred C++ comment style. In general, it is less error prone. Bracket-pair comment symbols can cause problems, particularly when one of the pair is omitted.

C ++ Examples

Here are two examples of using the rest-of-line comment symbol:

// C++: GCD program
const int N = 200; //N is the number of trials

The bracket-pair comment symbols are still useful, especially for lengthy, multi-line comments:

/*   * * * * * * * * * * * * * *
  Programmer: Alan Turing
  Compiler: Borland 5.0
  Modifications: 10-2-2022 cplusoop.com
*    * * * * * * * * * * * * * */

Comments versus Self-commenting Code

If you have the choice between comments and self-commenting code, choose the latter. It is better to have clear code with no comments than cryptic code with comments. There is a good reason for this. In actual practice, programs are modified and enhanced all the time. If the code explains itself, you just have to update it to new code that explains itself. If the code requires explanation, you have to update both the code and the explanation. If you forget to update the explanation, you end up with a comment that is worse than useless because it no longer reflects what is actually going on. The next person reading it must waste time trying to understand whether the code is wrong or the comment.

Function Comments

Comments are for human readers and not compilers, and there is no universal standard for the layout of a function comment. In this course, we will always use the following layout:

/**
Computes the value of an investment with compound interest.
@param initial_balance the initial value of the investment
@param p the interest rate per period in percent
@param n the number of periods the investment is held
@return the balance after n periods
*/
double future_value(double initial_balance, double p, int n){
 double b = initial_balance * pow(1 + p / 100, n);
 return b;
}

Discussion of Function Comments

The function comment does not document the implementation but the idea which is a more valuable property. According to the documentation style used in this course, every function (except main) must have a comment. The first part of the comment is a brief explanation of the function. Then supply an @param entry for each parameter, and an @return entry to describe the return value.
As you will see later, some functions have no parameters or return values. For those functions, @param or @return can be omitted. This particular documentation style is borrowed from the Java programming language and is called the javadoc style. There are a number of tools available that process C++ files and extract HTML pages containing a hyperlinked set of comments.

When comments are not necessary

Occasionally, you will find that the documentation comments are unnecessary to write. That is particularly true for general-purpose functions:

/**
Computes the maximum of two integers.
@param x an integer
@param y another integer
@return the larger of the two inputs
*/
int max(int x, int y)
{
 if (x > y)
  return x;
 else
  return y;
}

Adding Comments - exercise

Click the Exercise link below to provide comments to a program using the rest-of-line comment symbol.
Adding Comments - Exercise