SemmleCode Professional comes with a wide range of pre-packaged analyses, from architectural properties and metrics, to statement-level checks for likely bugs and violations of best practice.

Comment Ratio per Type in Each Package

This query shows the amount of documentation (comments) per class or interface, grouped by package. Red boxes represent types with little documentation, green boxes represent types with a lot of documentation. Library types, generated types and test classes are excluded from the tally.

How to Interpret the Query Results

Running this query on the source code of the Alfresco content management system yields the following result, displayed as a tree map:

Every individual box represents a type (i.e., class or interface), with types within the same package grouped together. The size of a box represents the code size of the corresponding type, and its colour the comment ratio. For a type T with l lines of code and c lines of comments, the ratio computed is c/(l+c+1), i.e. the ratio of comment lines to overall lines. Red represents a low comment ratio, green a high ratio.

When hovering the mouse pointer over a box, the number of lines of code and the comment ratio will be displayed:

Large, red or orange boxes deserve special attention, as they represent large types with a low comment ratio, which may be hard to understand. Alfresco is quite well-documented; the type Schema2XForms, for example, shows up as an orange box, i.e. it is relatively poorly documented compared to other types in the application. Even so, 13% of its non-blank lines are comments.

How to Address the Query Results

Carefully examine types showing up as large, red or orange boxes to determine whether they need additional documentation.

Source Code

import default

from RefType t, int code, int comment
where t.fromSource() and
      not (t instanceof GeneratedClass) and
      not (t instanceof TestClass) and
      code = t.getMetrics().getNumberOfLinesOfCode() and
      comment = t.getMetrics().getNumberOfCommentLines()
select t.getPackage() as Package,
       t as Type,
       code as LinesOfCode,
       ((float)comment) / (comment+code+1) as CommentRatio
order by LinesOfCode desc

References