...
Do not use the character sequence /* within a comment:
| Code Block | ||||
|---|---|---|---|---|
| ||||
/* comment with end comment marker unintentionally omitted security_critical_function(); /* some other comment */ |
...
Instead of using /* and */ to comment out blocks of code, comment out blocks of code using conditional compilation (for example, #if, #ifdef, or #ifndef).
| Code Block | ||||
|---|---|---|---|---|
| ||||
#if 0 /* use of critical security function no
* longer necessary */
security_critical_function();
/* some other comment */
#endif
|
...
The NOTREACHED comment tells some compilers and static analysis tools not to complain about this unreachable code. It also serves as documentation.
| Code Block | ||||
|---|---|---|---|---|
| ||||
if (0) { /* use of critical security function no
* longer necessary, for now */
/*NOTREACHED*/
security_critical_function();
/* some other comment */
}
|
...
These are some additional examples of comment styles that are confusing and should be avoided:
| Code Block | ||||
|---|---|---|---|---|
| ||||
// */ /* 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 to m = n + p; */
a = b //*divisor:*/c
+d; /* interpreted as a = b/c +d; in c90
* compiler and a = b+d; in c99 compiler */
|
...
Use a consistent style of commenting:
| Code Block | ||||
|---|---|---|---|---|
| ||||
/* Nice simple comment */ int i; /* counter */ |
...