Comment Density

Ratio of number of comments to number of statements

Description

This metric specifies the ratio of comments to statements expressed as a percentage.

Based on Hersteller Initiative Software (HIS) code complexity standard:

• Polyspace^® ignores these comments:

  • Comments that are included before the first statement. For instance, in this code, the first comment is ignored:

    // This function implements a hashtble
    extern void hashdef();

  • Comments that start with the source code line. For instance, this comment does not count as a comment for the metric but counts as a statement instead:

     remove(i); // Remove employee record

  • Comments that appear after the first line of a multiline comment. That is, multiline comments count as one comment. For instance, this is considered a single comment:

    // This function implements
    // regular maintenance on an internal database

• Polyspace calculates this metric after preprocessing the code. If your code contains macros, they are expanded before calculating the comment density.

• Polyspace does not count these statements:

  • Structure field and class member declarations

  • Template declarations

  • Class member function definition within the class

• A statement typically ends with a semicolon, but with some exceptions. Exceptions include semicolons in for loops or structure field declarations. For instance, the initialization, condition, and increment within parentheses in a for loop is counted as one statement. This statement counts as a single statement:

  for(i=0; i <100; i++)

  If you also declare the loop counter at initialization, that statement counts as two statements.

Polyspace does not calculate this metric for the included header files.

The recommended lower limit for this metric is 20. For better readability of your code, place at least one comment for every five statements. The value of this metric is clamped to 100. Such a value indicates that your code might contain more comment than statements.

To enforce limits on metrics, see Compute Code Complexity Metrics Using Polyspace.

Examples

Comment Density Calculation

    struct record {
    char name[40];
    long double salary;
    int isEmployed;
};

struct record dataBase[100];

struct record fetch(void);
void remove(int);

void maintenanceRoutines() {
// This function implements
// regular maintenance on an internal database
    int i;
    struct record tempRecord;

    for(i=0; i <100; i++) {
        tempRecord = fetch(); // This function fetches a record
        // from the database
        if(tempRecord.isEmployed == 0)
            remove(i);         // Remove employee record
        //from the database
    }
}

In this example, the comment density is 38. The calculation is done as shown in the table:

Code	Running Total of Comments	Running Total of Statements
struct record { char name[40]; long double salary; int isEmployed; };	0	1
struct record dataBase[100]; struct record fetch(void); void remove(int);	0	4
void maintenanceRoutines() {	0	4
// This function implements // regular maintenance on an internal database	1	4
int i; struct record tempRecord;	1	6
for(i=0; i <100; i++) {	1	6
tempRecord = fetch(); // This function fetches a record // from the database	2	7
if(tempRecord.isEmployed == 0) remove(i); // Remove employee record //from the database } }	3	8

There are three comments and eight statements. The comment density is 3/8*100 = 38.

Metric Information

Group: File

Acronym: COMF

HIS Metric: Yes