Do Comments follow Commenting Conventions? A Case Study in Java and Python

TL;DR

This study investigates whether Java and Python developers follow existing commenting style guidelines, revealing a focus on content over syntax and highlighting gaps in current conventions that can inform future comment quality tools.

Contribution

It provides an analysis of style guidelines versus actual developer practices in Java and Python, identifying gaps and areas for improving comment quality checking tools.

Findings

Most guidelines focus on comment content rather than syntax or formatting.

Developers often do not follow existing commenting conventions.

Current guidelines do not adequately address important developer concerns.

Abstract

Assessing code comment quality is known to be a difficult problem. A number of coding style guidelines have been created with the aim to encourage writing of informative, readable, and consistent comments. However, it is not clear from the research to date which specific aspects of comments the guidelines cover (e.g., syntax, content, structure). Furthermore, the extent to which developers follow these guidelines while writing code comments is unknown. We analyze various style guidelines in Java and Python and uncover that the majority of them address more the content aspect of the comments rather than syntax or formatting, but when considering the different types of information developers embed in comments and the concerns they raise on various online platforms about the commenting practices, existing comment conventions are not yet specified clearly enough, nor do they adequately cover important concerns. We also analyze commenting practices of developers in diverse projects to see the extent to which they follow the guidelines. Our results highlight the mismatch between developer commenting practices and style guidelines, and provide several focal points for the design and improvement of comment quality checking tools.