Every main programming language implements comments and every developer out there has written at least a few (comments, not languages).
What are the best practices regarding comments according to static analysis tools?
Comments
Steve McConnell wrote in Code Complete:
“Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’”
To some degree, I agree with this. Many times I have found myself writing a comment only to delete it and rethink the code.
Then again, it is true that while code can be self-explanatory, the reasoning behind it may not, and comments can transmit the context that the original programmer had.
Putting all that aside, and considering that we will all write a lot of comments in the code to come, here are some relevant patterns:
Ruby
Rubocop has five patterns related to comments:
All put together, the first four enforce line comments in plain ASCII with a preceding space. It’s basically a way of simplifying comments so make them more readable for everyone.
The last one is interesting, especially when compared with two other patterns from Java and JavaScript (keep reading), as instead of prohibiting comment annotations it actually enforces the way they should be used.
Related: Review of Ruby Static Analysis Tools.
Python
Pylint offers a pattern that identifies useless string statements:
- Prohibit useless string statements
While the pattern is not regarding comments themselves, it pertains something else that could be converted into one.
Related: Review of Python Static Analysis Tools.
Java
In Java we have three more patterns from CheckStyle and a few more from PMD:
- Controls the indentation between comments and surrounding code (CheckStyle)
- Requires that comments be the only thing on a line (CheckStyle)
- A check for TODO comments (CheckStyle)
- Detects uncommented main methods (CheckStyle)
- Prohibit uncommented empty constructors (PMD)
- Prohibit uncomment empty methods (PMD)
- Denotes whether comments are required for specific language elements (PMD)
- Determines whether the dimensions of non-header comments found are within the specified limits (PMD)
- Prohibits politically incorrect comments (PMD)
- Default Access Modifier (PMD)
The first one of these patterns is really interesting, as it makes total sense and I haven’t found it in other tools; comments should be indented according to their surrounding code, which means that:
// this comment looks good boolean bool = true;
but:
if (bool) {
bool = false;
//this comment looks odd
}
The second pattern enforces once again that comments be on a single line while the third one checks for TODO comments (I recently wrote about TODO comments here).
The fourth pattern and most of the ones from PMD are considerably different, as they are actually tied to the language itself. I also like the idea of the pattern to prohibit incorrect comments, but I fear to one day work in a team that actually requires it…
Related: Review of Java Static Analysis Tools.
JavaScript
ESLint gives us four comment-related patterns:
- Enforce empty lines around comments
- Prohibit inline comments
- Prohibit Warning Comments
- Require/Prohibit whitespace at beginning of a comment
- Require JSDoc comment
The first one has 10 different options you can use to make it better suit your preferences. Personally, I like comments with an empty line above them, but I also use comments with empty lines around them if they’re there to denote that a certain part of my code begins there:
// CONFIG
// this is a very important variable var something = "something";
The second and third patterns are something we’ve seen before: prohibiting inline comments and TODO comments (and the likes).
We’ve also seen the leading whitespace rule before (in Ruby), but this time we see the pattern with an option of making the whitespace required or prohibited.
The last pattern requires that all functions have JSDoc comments for documentation purposes (again, something tied to the language).
Final comments
(pun intended)
I really like to see how patterns differ from language to language (or from tool to tool) and what’s missing here and there.
I guess that any of these tools could implement at least some of patterns we see here from other tools. While they may be a matter of personal taste, there’s probably someone coding in each of these languages for whom the other patterns could be useful.
Personally, I like single line comments with an empty line above them, so I know which of these patterns I need enabled on my projects at Codacy.
Edit: We just published an ebook: “The Ultimate Guide to Code Review” based on a survey of 680+ developers. Enjoy!
About Codacy
Codacy is used by thousands of developers to analyze billions of lines of code every day!
Getting started is easy – and free! Just use your GitHub, Bitbucket or Google account to sign up.
