C++ Programming/Code/Style Conventions/Comments

Comments edit

Comments are portions of the code ignored by the compiler which allow the user to make simple notes in the relevant areas of the source code. Comments come either in block form or as single lines.

  • Single-line comments (informally, C++ style), start with // and continue until the end of the line. If the last character in a comment line is a \ the comment will continue in the next line.
  • Multi-line comments (informally, C style), start with /* and end with */.

Note:
Since the 1999 revision, C also allows C++ style comments, so the informal names are largely of historical interest that serves to make a distinction of the two methods of commenting.

We will now describe how a comment can be added to the source code, but not where, how, and when to comment; we will get into that later.

C style comments edit

If you use C style comments, try to use it like this:

Comment single line:

/*void EventLoop(); /**/

Comment multiple lines:

/*
void EventLoop();
void EventLoop();
/**/

This allows you to easily uncomment. For example:

Uncomment single line:

void EventLoop(); /**/

Uncomment multiple lines:

void EventLoop();
void EventLoop();
/**/

Note:
Some compilers may generate errors/warnings.
Try to avoid using C style inside a function because of the non nesting facility of C style (most editors now have some sort of coloring ability that prevents this kind of error, but it was very common to miss it, and you shouldn't make assumptions on how the code is read).

... by removing only the start of comment and so activating the next one, you did re-activate the commented code, because if you start a comment this way it will be valid until it finds the close of comment */.

Note:
Remember that C-style comments /* like this */ do not "nest", i.e., you can't write

int function() /* This is a comment */
{              
 return 0;  
}              and this is the same comment */
               so this isn't in the comment, and will give an error*/

because of the text so this is not in the comment */ at the end of the line, which is not inside the comment; the comment ends at the first */ sequence it finds, ignoring any interim /* sequence, which might look to human readers like the start of a nested comment.

C++ style comments edit

Examples:

// This is a single one line comment

or

if (expression) // This needs a comment
{
  statements;   
}
else
{
  statements;
}

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;
Using comments to temporarily ignore code

Comments are also sometimes used to enclose 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.

Example with C style comments
/* This is a single line comment */

or

/*
   This is a multiple line comment
*/
C and C++ style

Combining multi-line comments (/* */) with c++ comments (//) to comment out multiple lines of code:

Commenting out the code:

/*
void EventLoop();
void EventLoop();
void EventLoop();
void EventLoop();
void EventLoop();
//*/

uncommenting the code chunk

//*
void EventLoop();
void EventLoop();
void EventLoop();
void EventLoop();
void EventLoop();
//*/

This works because a //* is still a c++ comment. And //*/ acts as a c++ comment and a multi-line comment terminator. However this doesn't work if there are any multi-line comments are used for function descriptions.

Note on doing it with preprocessor statements

Another way (considered bad practice) is to selectively enable disable sections of code:

#if(0)   // Change this to 1 to uncomments.
void EventLoop();
#endif

this is considered a bad practice because the code often becomes illegible when several #if's are mixed, if you use them don't forget to add a comment at the #endif saying what #if it correspond

#if (FEATURE_1 == 1)
do_something;
#endif //FEATURE_1 == 1

you can prevent illegibility by using inline functions (often considered better than macros for legibility with no performance cost) containing only 2 sections in #if #else #endif

inline do_test()
  {
    #if (Feature_1 == 1)
      do_something
    #endif  //FEATURE_1 == 1
  }

and call

do_test();

in the program

Note:
The use of one-line C-style comments should be avoided as they are considered outdated. Mixing C and C++ style single-line comments is considered poor practice. One exception, that is commonly used, is to disable a specific part of code in the middle of a single line statement for test/debug purposes, in release code any need for such action should be removed.