Barr Group FacebookBarr Group TwitterBarr Group LinkedInBarr Group Vimeo

Rules

The following C coding rules relate to the acceptable formats for comments:

Rule 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., /* … */).

Rule 2.1.b.) Comments shall never be nested.

Rule 2.1.c.) Comments shall never be used to disable a block of code, even temporarily.

  1. To temporarily disable a block of code, use the preprocessor’s conditional compilation feature (e.g., #if 0 … #endif). No block of temporarily disabled code shall remain in the source code of a release candidate.
  2. Any line or block of code that exists specifically to increase the level of debugging output information shall be surrounded by #ifndef NDEBUG … #endif. In this way, useful debug code may be maintained in production code, as the ability to gather additional information is often desirable long after development is done.

Reasoning

Nested comments and commented-out code both run the risk of allowing unexpected snippets of code to be compiled into the final executable. This can happen, for example, in the case of sequences such as

/*
code-intentionally-disabled
/* comment */ 
code-unexpectedly-enabled
*/

Exceptions

None.

Enforcement

The use of only acceptable comment formats can be only partially enforced by the compiler or static analysis. The avoidance of commented-out code, for example, must be enforced during code reviews.

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

Sign up for our newsletter today!

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.