Mixing the use of traditional or block comments (starting with /* and ending with */) and end-of-line comments (from // to the end of the line) can lead to misleading and confusing code, which may result in errors.
Noncompliant Code Example
The following compliant code examples show mixed comments that may be misunderstood:
| Code Block | ||
|---|---|---|
| ||
// */ /* commentComment, not syntax error */ f = g/**//h; /* equivalentEquivalent to f = g / h; */ /*//*/ l(); /* equivalentEquivalent to l(); */ m = n//**/o + p; /* equivalentEquivalent to m = n + p; */ a = b //*divisor:*/c + d; /* equivalentEquivalent to a = b + d; */ |
Compliant Solution
Use a consistent style of commenting:
| Code Block | ||
|---|---|---|
| ||
// Nice simple comment int i; // counter Counter |
Noncompliant Code Example
There are other misuses of comments that should be avoided.
Noncompliant Code Example
Do not use the This noncompliant code example uses the character sequence /* within a comment: to begin a comment but neglects to use the delimiter */ to end the comment. Consequently, the call to the security-critical method is not executed. A reviewer examining this page could incorrectly assume that the code is executed.
| Code Block | ||
|---|---|---|
| ||
/* commentComment with end comment marker unintentionally omitted security_critical_method(); /* someSome other comment */ |
...
Using an editor that provides syntax highlighting or that formats the code to identify issues like such as missing end comment delimitors delimiters can help detect accidental omissions.
Because missing end delimitors delimiters are error prone and often viewed as a mistake, this approach is not recommended for commenting out code.
Compliant Solution
This compliant solution demonstrates the recommended way to mark code as "dead." It also takes advantage of the compiler's ability to remove unreachable (dead) code. The code inside the if block must remain acceptable to the compilerbe syntactically correct. If other parts of the program later change later in a way that would cause syntax errors, the unexecuted code must be brought up to date to correct the problem. Then, if it is needed again in the future, all the programmer must do is need only remove the surrounding if statement and the NOTREACHED comment.
The NOTREACHED comment could tell some compilers and static analysis tools not to complain about this unreachable code. It also serves as documentation.
| Code Block | ||
|---|---|---|
| ||
if (false) { /* useUse of critical security method no * longer necessary, for now */ /* NOTREACHED */ security_critical_method(); /* someSome other comment */ } |
This is an instance of exception MSC59-EX2 to MSC57-JGexample of an exceptional situation described in MSC56-J. Detect and remove dead superfluous code and values.
...
Applicability
Confusion over which instructions are executed and which are not can lead to serious programming errors and vulnerabilities, including denial of service, abnormal program termination, and data integrity violation. This problem is mitigated by the use of interactive development environments (IDEs) and editors that use fonts, colors, or other mechanisms to differentiate between comments and code. However, the problem can still manifest, for example, when reviewing source code printed on a black-and-white printer.
...
Guideline
...
Severity
...
Likelihood
...
Remediation Cost
...
Priority
...
Level
...
...
medium
...
unlikely
...
medium
...
P4
...
L3
Automated Detection
Nested block comments and inconsistent use of comments could be detected by suitable static analysis tools.
Related Vulnerabilities
Search for vulnerabilities resulting from the violation of this rule on the CERT website.
Related Guidelines
This guideline is based on MSC04-C. Use comments consistently and in a readable fashion and MSC04-CPP. Use comments consistently and in a readable fashion.
Bibliography
Bibliography
...