Comment density falls below threshold

The comment density of the module falls below the specified threshold

Since R2021a

Description

Polyspace^® calculates the comment density percentage of a file by taking the ratio of comments to number of executable lines in the file and then multiplying the ratio by 100. For instance, a comment density 20 indicates that the file contains 20% comments and 80% code statements. This defect is raised when the comment density falls below the specified threshold. For details about how Polyspace calculates comment density, see Comment Density

Polyspace uses the default threshold 80 unless you specify a threshold. To specify a selection file where you can set the threshold, use the option Set checkers by file (-checkers-selection-file) or Checkers activation file (-checkers-activation-file).

When you import comments from previous analyses by using polyspace-comments-import, Polyspace copies any review information on the code metric Comment Density in the previous result to this checker in the current result. If the current result contains the same code metric, the review information is copied to the code metric as well.

Risk

Violation of this checker might indicate that:

The module is not properly documented.
The module is overly long and dense.
The module might contain unexpected or unplanned development.

These factors make the module difficult to maintain and debug.

Fix

To fix this defect:

Put more comments between your statements that conveys the developer intent.
Alternatively, reduce the number of statements in the module. If the module contains multiple functions, consider splitting the module and documenting them separately.

To fix this check, either refactor your code or change the checker threshold. A best practice is to check the complexity of a module early in development to avoid costly post-development refactoring.

Examples

expand all

Avoid Poorly Documented Code

//File1.cpp        //Noncompliant
 long long power(double x, int n){
	 long long BN = 1;
	 for(int i = 0; i<n;++i){
		 BN*=x;
	 }
	 return BN;
 }
 
 double AppxIndex(double m, double f){
	 double U = (power(m,2) - 1)/(power(m,2)+2);
	 double V = (power(m,4) + 27*power(m,2)+38)/(2*power(m,2)+3);
	 return (1+2*f*power(U,2)*(1+power(m,2)*U*V + 
                power(m,3)/power(m,3)*(U-V)))/( (1-2*f*power(U,2)
              *(1+power(m,2)*U*V + power(m,3)/power(m,3)*(U-V))));
 }

In this example, the code in File1.cpp does not contain sufficient comments to document the developer intent. lack of sufficient documentation makes the code difficult to understand. Subsequent debugging and maintenance of the code might be difficult. Polyspace flags the file as noncompliant to this rule.

Correction — Document the Developer intent with Comments

One possible correction is to document the developer intent by putting sufficient comments. This code contains comment that clearly document developers intent and conveys information that eases understanding, debugging, and maintaining the code.

//File1.c        //Compliant
// r = power(x,n) returns the nth power of x into y
// r is long long
// x is double
// n must be integer
 long long power(double x, int n){
	 long long BN = 1;
	 for(int i = 0; i<n;++i){
		 BN*=x;
	 }
	 return BN;
 }
 // n = AppxIndex(m,f) calculates the approximate
//  effective index of a material
// n is a double, represent the effective index of a mixture
// m is a double, represents the relative index of the 
//                  inclusion compared to the background material
// f is a double, represents the filling factor of the inclusion
// The function implements the formula in the doi 10.XXYY 
 double AppxIndex(double m, double f){
	 // This function implements the formula for approximate index
	 // The first term is U:
	 double U = (power(m,2) - 1)/(power(m,2)+2);
	 //The second term is V:
	 double V = (power(m,4) + 27*power(m,2)+38)/(2*power(m,2)+3);
	 // Calculate the denominator
	 double den = ( (1-2*f*power(U,2)*
              (1+power(m,2)*U*V + power(m,3)/power(m,3)*(U-V))));
	 // Calculate the numerator
	 double num = (1+2*f*power(U,2)
              *(1+power(m,2)*U*V + power(m,3)/power(m,3)*(U-V)));
	 // Calculate the approximate index
	 // Return by value
	 return num/den;
 }

Check Information

Group: Software Complexity

Language: C | C++

Acronym: SC02

Default Threshold: 20

Version History

Introduced in R2021a