In this section, we will cover about all types of comments used in C++. Comments is often given least importance in coding but they are read much more time than the actual lines of code. They primarily serve to explain C++ code, increase its readability and decrease its cognitive complexity. Apart from giving basic information about the file, functions, author, year, change log etc. they often suggests why current implementation is chosen. It can also be used to prevent execution when testing alternative code.

A well-documented program is often one of the expected deliverable from a programmer. Comments makes a program more readable and easier to find error. Programmers often include tags to create low level documentation of the code. Comments also server an important purpose at code reviews. For e.g. a comment on top of a function giving its space and time complexity will help reviewer appreciate the function's efficiency and see how it impacts the overall module.

In almost all programming languages, a comment is a programmer-readable explanation or annotation to explain the code below. Comments are statements that are ignored by the compiler (they are not executed). In C++, Comments are both singled-lined and multi-lined.

Single-line Comments 🡪 begin with 2 forward slashes (//). Text sandwiched between // and the end of the line is ignored by the compiler (will not be executed).

// Output Hello World! to console
cout << "Hello World!";

This example uses a single-line comment before a line of code. The backslash is a continuation character and will continue the comment to the following line:

// This comment will also comment the following line \
std::cout << "This line will not print" << std::endl;

C++ Multi-line Comments 🡪 they start with /* and ends with */. Any text between /* and */ will be ignored by the compiler.

/*
 * The code below will print Hello World!
 * to the screen
 */
cout << "Hello World!";

As a general rule, each object in a C++ program should have a comment block, be it file, function, constant, macro, pre-processor, class etc. Any statement in your program that is not obvious  or complicated should be commented as well. Similarly, any use of external library function call should be annotated. Following is the example of a file header that is usually present at the top of source or header file

/********************************************************** 
 *
 * Program:      Hello World
 *
 * File:         Hello.cpp
 *
 * Function:     Main Entry point of the program
 *
 * Description:  Prints the words "Hello world" to the  
 *               screen
 *
 * Author:       Nikhil Jain [nj] (nikhil.XXX@gmail.com)
 *
 * Year:         2020-2021 
 * 
 * Environment:  g++ (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0.
 *
 * Notes:        This is an introductory, sample program.
 *
 * Revisions:    1.00  10/1/2020 (nj) First release
 *           
 *******************************************************/

Comments are also sometimes used to enclose experimental code or trial code that we temporarily want the compiler to ignore. This can be useful in finding errors in the program. If a program does not give the desired result, it might be possible to track which particular statement contains the error by commenting out code. The following comment block is placed above a function definition

The following is comment block for a class

/*-------------------------------------------------------
                    <copyright notice>

Determine if input type A is same as type B. Example:

template <typename T, typename U>
void do_something(const T&, const U&, bool flag);

template <typename T, typename U>
void do_something(const T& t, const U& u)
{
    do_something(t, u, is_same<T,U>::value);
}
---------------------------------------------------------*/

The following is good way to annotate a function so that its low level documentation can be created for further reference.

/// <summary>Sorts the list to by the given column</summary>
/// <param name="sel_criteria">Column to be sorted (index-1-based) and sort direction (pos. = ascending)</param>  
/// <returns>Documentation of return type</returns>  
void CDBTaglist::SetSorting(int sel_criteria) { ... }