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

Introducing Pulse to help companies achieve elite engineering performance

At Codacy, we envision a future where everyone can impact the world by crafting complex software with confidence and focus at the speed of...

First QA Engineer in a Startup

This is the story of how I joined a startup as the first QA Engineer in the company.  My name is Bruno Medley, I'm a...

Is your code secure with Codacy?

If you have been in the development business, you are well aware of the fact that data breaches are a part of the development...

8 Common Software Development Mistakes and How to Avoid Them

The world of software development is fast-paced and ever-changing. The queue of feature requests never seems to shrink. With the constant demand for improvements, adherence...

The Bundling and Unbundling of the DevOps market

The DevOps market continues to grow1: The global development and operations (DevOps) market size stood at USD 3,709.1 million in 2018 and is projected to...