Comparison of commenting conventions covered by style guidelines and tools

Introduction

Code comments are written in natural language and their syntax is neither imposed by a programming language's grammar nor checked by its compiler. Therefore, writing consistent comments across projects is a major concern. To motivate developers to write consistent and readable comments, various communities provide coding style guidelines, including, amongst others, naming conventions, formatting conventions, and commenting conventions.

Problem

What kinds of commenting conventions these style guidelines provide, is not explored. For example, “what information a class comment should contain” Is described differently in different programming language style guidelines. Oracle style guideline for Java mentions that class comments should contain summary, author description Whereas Python style guideline PEP257 mentions that class docstring should list its public methods and instance variables in addition to the summary. Similarly, the PHP style guide provides tag @internal to limit the audience of the documentation whereas the Oracle style guideline and the Python style guidelines do not mention any such concept. Collecting these commonalities and differences of comment conventions amongst popular style guidelines, we formulate first research questions.

To help developers in following these style guidelines while writing the comments, various automated style checkers (linters) exist, for example, Checkstyle, Pylint, PyDocStyle. However, which commenting conventions do these style checkers support in the form of supported rules, is another dimension to explore. We formulate another research question to explore this area.

Research Questions

Aim

Compare the commenting conventions mentioned in the style guidelines and checked by style checkers.

Steps

Note

The project can be extended to a thesis project.

Further Material

Contact

Pooja Rani

Assigned to

Michael Dooley