Use comments consistently and in a readable fashion

Non-Compliant Example

Do not use the character sequence /* within a comment:

/* comment with end comment marker unintentionally ommitted
...
security_critical_function();
/* some other comment */

In this example, the call to the security critical function is not executed. It is possible that, in reviewing this page, a reviewer may assume that the code is executed.

In cases where this is the result of an accidental ommision, it is useful to use an editor that provides syntax highlighting or formats the code to help identify issues like missing end comment deliminators.

Because missing end deliminators is error prone and often viewed as a mistake, it is recommended that this approach not be used to comment out code.

Compliant Example

Comment out blocks of code using condition compilation (e.g., #if or #ifdef).

#if 0  /* use of critical security function no longer necessary */
security_critical_function();
/* some other comment */
#endif

Non-Compliant Example

The following are some additional examples of comment styles that are confusing and should be avoided:

// */ // comment, not syntax error
...
f = g/**//h; // equivalent to f = g / h;
...
//\
i(); // part of a two-line comment
...
/\
/ j(); // part of a two-line comment
...
/*//*/ l(); // equivalent to l();
...
m = n//**/o
+ p; // equivalent tom = n + p;

Compliant Example 1

Use a consistent style of commenting:

// Nice simple comment

int i; // counter

Compliant Example 2

Use a consistent style of commenting:

/* Nice simple comment */

int i; /* counter */

References

• ISO/IEC 9899-1999 6.4.9 Comments
• MISRA 04 Rule 2.3 The character sequence /* shall not be used within a comment.