Barr Group TwitterBarr Group Vimeo

Rules:

2.1.a. Single-line comments in the C++ style (i.e., preceded by //) are a useful and acceptable alternative to traditional C style comments (i.e., /* … */).

2.1.b. Comments shall never contain the preprocessor tokens /*, //, or \.

2.1.c. Code shall never be commented out, even temporarily.

i. To temporarily disable a block of code, use the preprocessor’s conditional compilation feature (e.g., #if 0 … #endif).

ii. Any line or block of code that exists specifically to increase the level of debug output information shall be surrounded by #ifndef NDEBUG …#endif.

Example:

/* The following code was meant to be part of the build...
...
safety_checker();
...
/* ... but an end of comment character sequence was omitted. */

Reasoning: Whether intentional or not, nested comments run the risk of confusing source code reviewers about the chunks of the code that will be compiled and run. Our choice of negative-logic NDEBUG is deliberate, as that constant is also associated with disabling the assert() macro. In both cases, the programmer acts to disable the verbose code.

Enforcement: The use of only permitted comment formats can be partially enforced by the compiler or static analysis. However, only human code reviewers can tell the difference between commented-out code and comments containing descriptive code snippets.

What’s happening and how it’s done. Get in the know.

Sign Up for Our Newsletter

Receive free how-to articles, industry news, and the latest info on Barr Group webinars and training courses via email. 

To prevent automated spam submissions leave this field empty.