Home Education Programming languages: comparison of Best Practices, comments

Programming languages: comparison of Best Practices, comments

Author

Date

Category

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

LEAVE A REPLY

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

Free Codacy Pro account to fight COVID-19

Our hearts go out to everyone who has been directly or indirectly impacted by the global coronavirus (COVID-19) pandemic. We are committed...

Introducing GitHub Apps for improved user access control

We are very excited to announce our recent migration to GitHub Apps to improve the experience of GitHub Cloud users. Now, you...

How Agile & Container Technology led to the rise of enterprise DevSecOps

New development processes and open-source technologies have shifted the technology security landscape for enterprises. Previously a separate security department often dealt with...

Spring tech events with Codacy: Coverage & what's next

Although many Spring tech events are being canceled or turning virtual due to coronavirus we are fortunate to have already participated in...

Top 6 items for your code review checklist

At Codacy we set high standards, and care about the quality of the code we produce. In order to provide optimal experiences...