The Importance of Quality Comments

Do you let the code speak for itself? Or do you comment until the cows come home?

At Mobile Jazz we develop mobile apps and websites for our customers. We’re committed to delivering high quality software, and for us that means paying attention right down to the smallest detail.

A timeless hot topic among developers is commenting on the code. Even within our team we hold animated internal discussions on this: Some people rarely comment on their code, while others like to throw in a bucketload.

One of the main purposes of adding comments is to aid future work. In our case this is particularly crucial, as it enables us to work on different projects at the same time or work on a project every X months only.

Let’s look at a real example from some code we inherited from one of our developers. We came across a problem that should have been a breeze to solve. But, because of a poorly constructed comment, it quickly turned into a real headache.

Here’s the screenshot:

As you can see, the comment makes it clear that there’s a custom library jar, but this doesn’t really help us. Here’s why:

• Usually, comments are placed before the code it refers to, not after. In this case, the comment refers to volley.jar library. So that’s a mistake from the developer; the whole team should be consistent when adding comments to the code.
• The description doesn’t provide any information, it just says we are using a custom jar for some unknown reason. It would be much better if we knew why those changes were needed.
• It doesn’t point out the location of the custom library’s source code, or how to build it.

As you can see, comments are important. Usually developers don’t pay too much attention to the comments because, to them, what they’re working on is obvious.

Imagine, however, that this particular developer leaves the company. So, too, do the rest of the team over a 2-year period. Now there’s no-one in the company that understands the comment, and when a new developer needs to delve back into the code—whoops, there’s no way of knowing what’s going on. This is exactly what happened in this example.

Also, you should always document any change you make to an existing library and keep the code of the modified version. Then, you can add a link to the code and the document of changes, via the comment itself. If you are using a public library available in GitHub, it’s a good idea to create a branch of the original library and keep the modified version in your GitHub account.

Do too many cooks spoil the broth? Absolutely not.

It’s always better to have too many comments than none at all. In my case, for example, I work on a lot of different projects and languages at the same time, so for me having comments on the code helps massively when it comes to quickly understanding what’s going on.

Let’s take a look at another example, this time of code with quality comments.

The following screenshot contains some GO code from Bugfender. Even if you don’t understand GO and don’t know anything about Bugfender you can easily follow what’s happening the code:

Yes, most of the comments might look redundant as the code is quite clean and clear, but having the comments in plain text allows anyone to understand what the function is doing in just a couple of seconds. There’s no need to understand GO or the models in the product. It makes it so much easier if you then want to delve deeper into a particular area of the code.

Now, take a look at the following screenshot of some previous code we inherited from a client:

Yes, there are some comments in the code, but it’s really hard to understand what the code is doing even with the comments as they don’t provide enough information.

The more complex the code, the more comments it should have.

Conclusion

At Bugfender and Mobile Jazz, we take code quality very seriously. We always ensure our projects are written with clean, clear code that can be easily understood and transferred to our clients.

Here’s our blueprint for writing comments:

• Comments are key. Write them!
• Think about the future of the code/app. You might not be around or perhaps you’re not going to revisit it for a couple of years. Will you be able to understand the code in one year from now?
• When you write comments, imagine reading them through the eyes of another developer seeing them for the first time. Do they make sense?
• Document/save any changes you make to a library. A must if you’re building a project.

Do you have any commenting rules in your company? Share them with us!