Comparing best practices across programming languages: comments

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:

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:

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:

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.

enforce empty lines around comments

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.

GET STARTED

Best Practices

Related Articles