Adherence of class comments to style guidelines

Suada Abukar. Adherence of class comments to style guidelines. Bachelor’s thesis, University of Bern, August 2021. Details.


Code comments play an important role in program comprehension and maintenance tasks. They are written in natural language and follow a semi-structured or unstructured nature. Due to this, assessing their quality is a difficult task. To control certain aspects of quality such as consistency, readability, or preciseness, programming languages provide comment-related conventions in the coding style guidelines. One of the ways to assess comment quality in mentioned aspects is to verify if the code follows the respective coding style guidelines or not. However, what specific types of conventions they suggest related to code comments and if developers follow these conventions while writing comments is not yet explored. Previous works have proposed to automatically assess code quality using various linters or static tools. However, the extent to which these tools support comments is limited and comment validation on a semantic level is not provided. Additionally, one project can follow more than one style guideline. Thus, verifying which convention is from which guideline and to what extent it is followed is an essential but nontrivial task. This thesis provides an empirical study investigation of the content of popular commenting style guidelines and commenting practices in Java and Python. We extract comment-related rules from style guidelines used by 13 open-source projects. Furthermore, we assess nearly 700 statistically significant samples of class comments originating from these 13 projects. The projects vary in domain, size, and number of contributors and are selected from two popular programming languages: Java and Python. This thesis uncovers the quality of class comments written in open-source projects and the content of the comment style guide. We discovered that 57% of the comment conventions rules do not apply to the class comment samples. From the applicable portion, most class comments follow the convention rules. The rules that are followed by the comments the most were mostly rules about the content and writing style of comments. Our results highlight the importance of writing clear and straightforward rules in the style guidelines since they are used and interpreted by developers with different levels of coding experience. In addition, the high percentage of adherence proves that developers do consult style guidelines when coding.

Posted by scg at 1 September 2021, 11:15 am link
Last changed by admin on 21 April 2009