MISRA C:2012 Dir 4.4

Sections of code should not be "commented out"

Since R2020b

Description

Directive Definition

Sections of code should not be "commented out".

Rationale

C comments enclosed in /* */ do not support nesting. A comment beginning with /* ends at the first */ even when the */ is intended as the end of a later nested comment. If a section of code that is commented out already contains comments, you can encounter compilation errors (or at least comment out less code than you intend).

Commenting out code is not a good practice. The commented out code can remain out of sync with the surrounding code without causing compilation errors. Later, if you uncomment the code, you can encounter unexpected issues.

Use comments only to explain aspects of the code that are not apparent from the code itself.

Polyspace Implementation

The checker uses internal heuristics to detect commented out code. For instance, characters such as #, ;, { or } indicate comments that might potentially contain code. These comments are then evaluated against other metrics to determine the likelihood of code masquerading as comment. For instance, several successive words without a symbol in between reduces this likelihood.

The checker does not flag the following comments even if they contain code:

Doxygen comments beginning with /**, /*!, /// or //!.
Comments that repeat the same symbol more than five times, for instance, the symbol = here:
```
/* =====================================
 * A comment
 * =====================================*/
```
Comments on the first line of a file.
Comments that mix the C style (/* */) and C++ style (//).
Comments that contain one or more @ symbol. If the @ symbol is placed in a nested comment that contains code, Polyspace^® flags it. For instance:.
```
int* q;
//@Error int foo(void);
//...
void bar(void){
	/*
	int*p =  (int*) malloc(int); // Error @allocation
	*/
}
```
In the preceding code, Polyspace flags the second comment block containing the commented out malloc operation, and ignores the first comment.

The checker considers that these comments are meant for documentation purposes or entered deliberately with some forethought.

Troubleshooting

If you expect a rule violation but do not see it, refer to Diagnose Why Coding Standard Violations Do Not Appear as Expected.

Examples

expand all

Code Commented Out

#include <stdlib.h>
/* =====================================
 * usage:print32_tInteger(); 
 * =====================================*/
int32_t getRandInt();
void print32_t(int32_t);

//Error@ int32_t val = getRandInt();
void print32_tInteger() {
    /* int32_t val = getRandInt(); //Noncompliant
     * val++;  // contact support @..
     * print32_t(val); */     
    print32_t(getRandInt());
}

This example contains several comments that contains code.

The first comment block documents the usage of the function print32_tInteger(). Because the comment uses the symbol = more than five times, Polyspace does not flag this comment.
The second comment documents the source of error in the code. Because the code contains the symbol @, Polyspace ignores the comment.
The third comment block comments out code that might contain errors. This comment does not document anything and simply excludes code from compilation. Polyspace flags this code block. Because the @ symbol is in a nested comment, Polyspace does not ignore the comment.

Check Information

Group: Code design

Category: Advisory

AGC Category: Advisory

Version History

Introduced in R2020b