Developers: Stop Writing These Comments!
By: Kevin Van Ryckegem
Tags: Best Practices, Development, JavaScript, Programming, Software Development

Example Comments

Let’s go through some example comments and see how these are performing. Afterward, we can define some rules to make comments more efficient and useful for developers.

Example #1: The “what” comment

Have a look at the following example, and make up your mind regarding this commenting style.

The comments seem to be duplicates of the code, while the code is already very readable by itself. The comments are redundant in this case and not necessary. Developers can easily read the code and understand what’s happening. Let’s simplify this example.

Isn’t this much easier to read? The code is quite self-explanatory. We can simplify this even further. Not in terms of comments, but in terms of re-usable and readable abstractions.

How does that read? It practically reads like a book. Find all the users, increment the score for all users and finally return the users.

Readability in code is very important, it is even more important than good comments. When your code is very complex, abstract it, make it more readable. Is there absolutely 100% no way to make it simpler and more readable? Then add a short and clear comment explaining what it does.

If you can only choose between readable code or code with good comments — definitely choose readable code.

Example #2: The copied comment

The comments above do not match the code at all! Seeing how the code looks similar to one of our previous examples, the comments were probably copied over. The developer did not update the comments to match the code.

Make sure to always update your comments when copying existing code. If you find you need to copy code, there usually is a way to abstract it and make it re-usable. What do you think about the next piece of code?

We abstracted the logic of mass updating user score, and made it re-usable in the sense that the amount of score to be updated can be given. We now can re-use it in both scenarios instead of having copied the code.

Example #3: The Long JSDoc comment

For the next comment, I don’t expect you to read it all, just have a quick look. What do you think?

Code is not meant to be a book. While I’m all for JSDoc comments if the team agrees, comments in code should be efficient. Having to read a JSDoc comment for 10 minutes before understanding what a function does is not my definition of efficient.

Keep your comments strictly to necessary information, short and clear is the message.

If developers want to read articles, they can do so on Medium instead of in the codebase. If your comment is that long, there are high chances developers will not even read it. They might even forget to update the comment as they would try to ignore it.

Example #4: The Short JSDoc comment

We have seen an example of a long JSDoc comment, let’s take a look at a short JSDoc comment next.

This is another extreme case, but I have witnessed these kinds of comments in real codebases, and it does happen. While this is semi-useful for the JSDoc generation with the expected result, it is not even complete because it is missing some parameters.

If you do decide to use JSDoc in your codebase, don’t go half-the way, do it correctly from the start and keep it clean. It is an extra effort, which will pay off in the long-run for maintaining the software. Be strict in pull requests, and make sure the comments are well-maintained.

Example #5: The outdated JSDoc comment

In this example, we can see the developer has forgotten to update the JSDoc comment to match what the function actually does. The updateScoreForUsers function now also gives VIP users 500 extra score! This is not described in the comment, nor why this is the case.

Example #6: The why comment

This is one of my favorite types of comments. Let’s take a look.

In this case, we can understand VIPs are supposed to receive 500 extra score. There is no way a developer can be confused and accidentally change this behavior due to unclear requirements.

We are adding useful extra information in the code while keeping it short and understandable. The why for this code is something developers could guess, but not be sure about. With this extra comment, any doubts are removed, and developers do not have to be afraid to modify the function.

Of course, the requirements should also be clear. In practice, the original requirements will not always be documented very clearly. This is especially the case for applications that have been moved around different development teams.In ideal situations with great documentation and requirements, this specific comment might not be needed.

If we look at the second comment regarding the database, we can see another good example of where comments can be useful. When developers are using code in a non-traditional way due to specific bugs, or limitations, it can be helpful to add a why-comment, as other developers won’t understand why this was set in place in such a strange way. They might even remove the hotfix and cause issues if a comment doesn’t warn them.

At some point, I came across a virtual machine being run inside another virtual machine due to specific limitations in the setup to be able to fulfill our requirements. A comment mentioning this limitation and why the second virtual is being started up is certainly useful. In most cases we don’t need to comment on what is happening, since clear and readable code should cover that. What we cannot know, however, is the why.

Summary

Comments can play an important part in development, however, readable code is generally more important. There are many different ways to write code, but here are some guidelines I recommend:

Write short and clear comments : developers do not want to read books in the codebase

: developers do not want to read books in the codebase Explain the why, not the what : if the code is readable, the “what” should generally be self-explanatory. The “why” can only be guessed or assumed by developers. Developers should know never to assume or guess!

: if the code is readable, the “what” should generally be self-explanatory. The “why” can only be guessed or assumed by developers. Maintain your comments : keep them up to date! If you change the code, you should also update any previous comments related to this code. Your colleagues and your future self will thank you for it.

: keep them up to date! If you change the code, you should also update any previous comments related to this code. User Clear Commit Messages : This could be another article by itself but do spend some extra effort making the commit messages clear and useful.

: This could be another article by itself but do spend some extra effort making the commit messages clear and useful. Write Readable Code: More important than comments, is to have readable code.

Extra Resources