Main Content

Function Comment Density

Ratio of number of comments to number of statements in function

expand all in page

Description

This metric specifies the ratio of comments to statements in a function expressed as a percentage:

Function Comment Density = 100 * (Number of comments associated with a function / Number of statements in function body)

Polyspace® considers these comment blocks to be associated with a function:

  • Comment blocks immediately preceding a function

  • Comment blocks between the first token of the function declaration and the final brace of the function.

When counting comments for this metric, Polyspace:

  • Counts multiline comments as a single comment, regardless of spacing or indentation.

  • Counts the header comments for functions. Consider this code:

    //Comment
void foo() {}
    Polyspace counts the comment //Comment when calculating the function comment density. For the file-level metric Comment Density, comments that occur before the first statement are ignored.

  • Counts comments that start with a code line. Consider this code:

    int  var = 5; // variable
    Polyspace counts the comment //variable when calculating function comment density. For the file-level metric Comment Density, such comments are ignored.

The number of statements in the function body is based on the number of semicolons in the function after the code is preprocessed and the macros are expanded. For details about how statements are counted for this metric, see Comment Density.

Polyspace does not calculate this metric for these functions:

  • Functions that are declared but not defined

  • Function templates

  • Member functions of a class template

  • Defaulted or deleted class member functions

Examples

expand all

In this example, when calculating function comment density for foo(), Polyspace considers the entire block of comment preceding the function as one comment. Then, each comment line starting from the first token of the function declaration, int, is counted as one comment. The comments following the closing brace of the function (}) is not counted.

/*=============================*/
/* external linkage functions  */
/*=============================*/

// routine foo
/* arg1:
 *
 * arg2:
 */
// return a negative in case of error
// This comments block counts as function header comment; nComment = 1;



int /* return int type, counted as comments block;       nComment = 3
     */ foo (
         /* void */ // counted as comments block;        nComment = 3
         ) {        // counted as comments block 
    /* local variables */ //Consecutive comment lines considred same comment;  nComment =4
    int
        x; /* uninitailized at the declaration */ // counted as comments block; nComment =5

    int r =
#if 1
        0;
#else
    -1;
#endif

    return r;
    /* same line as '}' counted as comment block; nComment =6 */} /* same line but after '}' not counted
                                                       * as comment block for this function
                                                       */
													   /* This is a header comments for next function
                                        * even if not correctly indented. */

Here, the number of comments (nComment) is 6. After preprocessing, the number of statements is 3, resulting in a function comment density of 200%.

Metric Information

Group: Function
Acronym: FCOMF
HIS Metric : No

See Also