How Good is Your Comment? A Study of Comments in Java Programs

Reviewer: Andrew Brooks

To understand how developers comment, the Java code for three open-source projects was analyzed. Assuming a comment precedes the relevant program construct, an automatic analysis found that abstract methods, class declarations, interface declarations, and package declarations were almost always commented, while 61.1 percent of methods and 66.7 percent of constructors were commented. Interestingly, for DrJava, 54.1 percent of field declarations were commented, but only 3.5 percent of such program constructs were commented for SweetHome3D. The automatic analysis could have usefully quantified Javadoc usage, but did not. Forty-nine programmers also manually categorized a subset of comments from the three open-source projects according to a taxonomy. Based on categorizations of 407 comments, it was found that 73 percent of comments preceded the relevant program construct, 71 percent of comments were explicative in nature, and 80 percent of explicative comments were explicit in nature, that is, written in terms of program keywords. Table 5 reveals that 29 percent of comments were judged to be poor. Of note, around half of all assignment and control flow comments were judged to be poor. The programmers also answered a questionnaire about their own commenting habits. In general, responses matched the findings already obtained. Figure 8, however, reveals that 44 percent of the programmers indicated that they use comments to express pre- and post- conditions. These important comment forms appear to have been overlooked when the categorizing taxonomy was developed. Despite the criticisms above, this paper does provide useful insights into commenting habits and is recommended for software engineers and those researching software quality assurance. Online Computing Reviews Service