Home Education Programming languages: comparison of Best Practices, comments

Programming languages: comparison of Best Practices, 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?


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:


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.


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.


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;


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.


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:

// 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.



Please enter your comment!
Please enter your name here

Subscribe to our newsletter

To be updated with all the latest news, offers and special announcements.

Recent posts

February’s Product Update: 1-Click Autofixes for GitHub, New People Experience and more 🚀

Welcome to our monthly product update! We’ve been working hard over the past month and have some exciting updates for you below. 🥳 We want...

Interview with Daniel Pfeiffer, CTO at Firstbird

We had a very nice talk with Daniel Pfeiffer, CTO at Firstbird; it was an informal conversation in which we looked to understand the reasons why...

Add a Custom Host to Kubernetes

I’ve been working with different MicroK8s instances a lot in the last months. Microk8s, from my point of view, it’s the absolutely perfect abstraction for deploying...

Deciphering Javascript Checkers: Know Why and When You Might Use Them

We’re all familiar with rules of grammar, which aid in communication by letting us know when to use a comma, how to spell a...

Interview with Felipe Adorno, CTO at Monkey Exchange

We have talked with Felipe Adorno, CTO at Monkey Exchange, to better understand what made the company opt for an automated code review tool...