Do comments follow commenting conventions?
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 PDF: https://arxiv.org/pdf/2108.10766v2 Replication Package: https://doi.org/10.5281/zenodo.5296443 YouTube: https://youtu.be/mX_9XxQTSxQ
Recommended
Recommended
More Related Content
Recently uploaded
Recently uploaded (20)
Featured
Featured (20)
Do comments follow commenting conventions?
- 1. Do Comments follow commenting conventions? A case study in Java and Python Pooja Rani, Suada Abukar, Nataliia Stulova, Alexandre Bergel, Oscar Nierstrasz University of Bern, Switzerland
- 2. 2 /** Event fired when a spacer element is hidden or shown in Escalator * * @author Vaadin Lt d * @since 7.7.13 * / public class SpacerVisibili { System.out.println(..) ; }
- 3. 3 // This class fires an Event when a spacer element is hidden or shown in the Escalator. I am the author of this class . // It is present in the project since the version 7.7.13 and might delete in the next versions. public class SpacerVisibili { System.out.println(..) ; } No strict convention for their style & syntax
- 4. 4 E.g., Oracle comment guidelines Coding Style guidelines First sentence should summarise the class Use phrases instead of complete sentences Use third person instead of second person
- 5. /** Event fired when a spacer element is hidden or shown in Escalator * * @author Vaadin Lt d * @since 7.7.13 */ 5 Does this comment follow the guidelines? Does it not? First sentence should summarise the class Use phrases instead of complete sentences Use third person instead of second person Do developers follow these guidelines?
- 6. /** Event fired when a spacer element is hidden or shown in Escalator * * @author Vaadin Lt d * @since 7.7.13 */ 6 Does this comment follow the guidelines? Does it not? First sentence should summarise the class Use phrases instead of complete sentences Use third person instead of second person
- 7. 7 Analyzed Smalltalk class comments against the style guidelines but what about other languages? Java, Python Analyzed Java and Python class comments but not against the style guidelines. Methodology Dataset Do developers follow commenting guidelines for Java and Python comments? Previous works by Rani et.al.,
- 8. 8 Apache Hadoop Apache Spark Eclipse.cdt Google Guava Google Guice Django iPython Mailpile Pandas Pipenv PyTorch Requests Dataset
- 9. 9 Extracting guidelines Identifying rules Validate comments Create taxonomy Class comments Projects 1 2 3 4 5 Methodology
- 10. 10 Apache Hadoop Apache Spark Eclipse.cdt Google Guava Google Guice Django Pipenv Mailpile Request iPython Pandas PyTorch Oracle Google PEP8/257 Numpy Google 1 Extracting guidelines
- 11. 11 ●PEP 257 -- Docstring Conventions | Python.org 2 Identifying rules
- 12. 12 ●PEP 257 -- Docstring Conventions | Python.org 3 Content Formatting Content Formatting Formatting Formatting Create taxonomy
- 13. 13 Content rules are more prevalent in style guidelines but hard to locate RQ1: Types of comment conventions?
- 14. 14 Developers do not always adopt comment conventions (Not applicable rules) 49% 16% 47% 11% 54% 49% 38% 27% 32% 25% 24% 63% 53% 7% 2% 10% 3% 6% 10% 12% 3% 3% 2% 2% 3% 2% 44% 83% 43% 86% 40% 42% 50% 70% 65% 73% 74% 35% 45% Django iPython Mailpile Pandas Pipenv Pytorch Requests Eclipse Vaadin Spark Hadoop Guava Guice Python Java Followed rules Not followed rules Not applicable rules RQ2: Do developers follow conventions?
- 15. 15 /** @author Vaadin Ltd * * @since 7.7.13 */ First sentence should summarise the class Use phrases instead of complete sentences Use third person instead of second person RQ2: Do developers follow conventions? 27% 32% 25% 24% 63% 53% 3% 3% 2% 2% 3% 2% 70% 65% 73% 74% 35% 45% se in rk op va ce Followed rules Not followed rules Not applicable rules 63% 53% 3% 3% 2% 2% 3% 2% 70% 65% 73% 74% 35% 45% ules Not followed rules Not applicable rules 49% 16% 47% 11% 54% 49% 38% 27% 32% 25% 24% 63% 53% 7% 2% 10% 3% 6% 10% 12% 3% 3% 2% 2% 3% 2% 44% 83% 43% 86% 40% 42% 50% 70% 65% 73% 74% 35% 45% Django iPython Mailpile Pandas Pipenv Pytorch Requests Eclipse Vaadin Spark Hadoop Guava Guice Python Java Followed rules Not followed rules Not applicable rules
- 16. 16 Comments often follow writing style and content rules than other rule types RQ2: Do developers follow conventions?
- 17. 17 Verify other types of comments (Method, inline comments) Verify comments of other languages (C++, JavaScript) Develop tools to validate comments against the guidelines Improve comment quality assessment Future work
- 18. Preprint on Arxiv https://arxiv.org/pdf/2108.10766v2 Video on YouTube https://youtu.be/mX_9XxQTSxQ Replication Package on Zenodo https://doi.org/10.5281/zenodo.5296443 Contact us 18 https://twitter.com/poojaruhal http://scg.unibe.ch/staff Do Comments follow Commenting Conventions? A Case Study in Java and Python