Skip to end of metadata
Go to start of metadata

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:

// */                  /* Comment, not syntax error */

f = g/**//h;           /* Equivalent to f = g / h; */

/*//*/ l();            /* Equivalent to l(); */

m = n//**/o
+ p;                   /* Equivalent to m = n + p; */

a = b //*divisor:*/c 
+ d;                   /* Equivalent to a = b + d; */

Compliant Solution

Use a consistent style of commenting:

// Nice simple comment

int i; // Counter

Noncompliant Code Example

There are other misuses of comments that should be avoided. This noncompliant code example uses the character sequence /* 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.

/* Comment with end comment marker unintentionally omitted
security_critical_method();
/* Some other comment */

Using an editor that provides syntax highlighting or that formats the code to identify issues such as missing end comment delimiters can help detect accidental omissions.

Because missing end 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 be syntactically correct. If other parts of the program later change 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, the programmer 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.

if (false) {  /* Use of critical security method no
               * longer necessary, for now */
  /* NOTREACHED */
  security_critical_method();
  /* Some other comment */
}

This is an example of an exceptional situation described in MSC56-J. Detect and remove 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.

Nested block comments and inconsistent use of comments could be detected by suitable static analysis tools.

Bibliography

 


7 Comments

    • The first NCE is really extreme, can we get a couple of suitable errors people have made?
    1. This rule needs a good deal more love.

      • It need a serious introduction.
      • Also, this rule refers to nonexistent exception EX2 in MSC57-JG.
      1. I think that the introduction is OK.

        I've fixed the reference to the nonexistent exception.

        1. Thanks for the ref fix. The introduction was lifted from the corresponding C rule's first NCCE text. So this rule's intro is OK but we need some text for the 1st NCCE.

          1. I've added a sentence to the first NCCE.  I hope that's enough.

  1. perhaps we should also endorse this canonical block comment style:

    /*************************
     *
     *
     *************************/

    (Note the presence of a space-* pair at the beginning of each internal line in the block!)  It's common enough, and it provides enough visual redundancy that it may be worthy of mention.

    1. Dean, you don't mean javadoc comments right?

      /**

      *

      **/