Code Documentation Analysis

Description

This guide groups all the metrics related to Documenting and Comments that are used to evaluate the quality of the documentation of a software project.

It is always important to have reliable documentation to guide the work performed by the maintenance team. This team usually handles multiple applications at the same time, which means that it is even more crucial to have documentation in place to help track all aspects of each application. It is also helpful for development, maintenance, and knowledge transfer to other developers.

The following metrics defined by SonarQube give a quick overview of the application documentation state by measuring factors like the number of comments, the ratio between comments an lines of code, etc.

Metrics

  • Commented lines
    Number of lines containing either comment or commented-out code.

    Non-significant comment lines (empty comment lines, comment lines containing only special characters, etc.) do not increase the number of comment lines. The following piece of code contains 9 comment lines:

    /**                                    +0 => empty comment line
     *                                     +0 => empty comment line
     * This is my documentation            +1 => significant comment
     * although I don't                    +1 => significant comment
     * have much                           +1 => significant comment
     * to say                              +1 => significant comment
     *                                     +0 => empty comment line
     ***************************           +0 => non-significant comment
     *                                     +0 => empty comment line
     * blabla...                           +1 => significant comment
     */                                    +0 => empty comment line
    
    /**                                    +0 => empty comment line
     * public String foo() {               +1 => commented-out code
     *   System.out.println(message);      +1 => commented-out code
     *   return message;                   +1 => commented-out code
     * }                                   +1 => commented-out code
     */                                    +0 => empty comment line
    
  • Comments (%)

    Density of comment lines = Comment lines / (Lines of code + Comment lines) * 100
    
    With such a formula:

    • 50% means that the number of lines of code equals the number of comment lines
    • 100% means that the file only contains comment lines
  • Public documented API (%)

    Density of public documented API = (Public API - Public undocumented API) / Public API * 100
    

  • Public undocumented API
    Public API without comments header.

  • Commented-out LOC
    Commented lines of code

  • Public API
    Public classes, interfaces, methods, constructors, annotations and attributes.
    The following objects are excluded:

    • static final attribute
    • method with @Override annotation
    • empty constructor with no parameters
    • accessors (getters and setters) if the "sonar.squid.analyse.property.accessors" property is set to "true" (default value)

    In other languagues, as Cobol, the Public API is determined by Paragraph: * that does not only contain an EXIT statement * that is not the last paragraph in a module (ex: PERFORM FOO THRU BAR, BAR is not considered as an API)

    A paragraph is considered as being documented if there is a comment right before or right after the paragraph name