A short comment on comments in the code

My short comment on why you should stop using comments in your code (unless in special cases)

Tl;dr

Please, think twice before adding comments to your code. Probably, there are no needed and will just confuse people who will read your code later on. Write a clean, readable code instead. Thanks in advance!

Intro

I was thinking about this article for a very long time. As I often help young developers I see how many of them love adding comments to their code. And I still remember lecturers from my studies who tried to convince us that the good code should be commented to be readable for other developers. However, the last straw that breaks the camel’s back was the tweet you can see below.

Source: Programmers Memes Twitter

This photo is the best comment on adding comments to the code ever. I wish I could say it’s an exaggeration. But what is the difference between the above and the comment in the function below?

// function to count the perimeter of the triangle
// input: 3 numbers, output: number
const countTrianglePertimeter = (a: number, b: number, c: number)
: number => {
    return a + b + c;
}

Unfortunately, we can still find a lot of snippets like that in the code. And I strongly encourage you to avoid them! Why? There are many reasons to stop adding useless comments to your code.

Reasons to stop adding comments to your code

Comments are just redundant to the code

Very often comments do not provide any additional information to the user. They describe exactly the same things as the code does. So why duplicate the info for the reader? Use meaningful names instead. Extract logic to separate functions if needed. Extract const values to the well-named const variables. Simplify code e.g. using fast returning and avoiding multiple nesting if needed. Well-written code is even easier to read by non-native English speakers than long descriptions in plain language!

Comments are often out-to-date

The code in live projects changes. There are always some bug fixes or new functionalities which require not only adding the code but also editing the existing source. And as long as code is always up-to-date, hardly anyone remembers about updating the comments. So, comments are often out-to-date and present the old logic of the code. Remember, comments can lie — the code never does!

Comments can be misleading

Programmers very often want to keep comments short and write them after writing the code. Because of that, the text can contain some mental shortcuts and simplifications. What is hidden between the words may be obvious to the author, but not to the reader. Using the wrong word may make the whole meaning completely different. And when you make a mistake in the code — tests will catch it. Unfortunately, there is no automated way to test if your comment is not misleading. So just skip it — as long as it’s possible.

Comments make the source code longer

It’s quite obvious — each comment’s line makes your code file longer. And our brains don’t like long walls of text. Opening a file with many comments makes it difficult to find really important lines and see all the code on the screen. When you can’t see all functions on one screen it’s easier to make mistakes or create some inconsistency. Also, computers have to handle it, so it may have an impact on performance. For many years, fans of the minimalist approach to life have been saying that fewer things mean less chaos. And I agree with them — at least when it comes to programming.

Everyone is afraid of removing or uncommenting commented code

Sometimes we leave the code commented in case it will be useful in the future. But let’s be honest — there are no more scary things than code that is commented on and no one knows why. Can we just remove it? Why it’s not working? What happens if we uncomment it? Leaving unfinished or “almost working” snippets commented in the code could be useful many years ago. But now we have great code versioning systems like git — removing the code with meaningful and descriptive commit message (and eventually adding a tag to make it easier to find later on) is much more convenient, clear, and easy to revert. Also, almost no one starts the implementation of a new feature by looking for some commented code in the codebase. So chances that someone will use your currently unnecessary code are really low.

Special cases when comments can be useful

In the previous section, I described many reasons for removing comments from your code. However, there are some special cases where comments can be useful — even in the production code! They are described below — but remember: I don’t call them special cases by accident :)

Regexes

There is an old saying “If you have a problem and use regex to solve it then you have two problems”. Regular expressions are great and useful but unfortunately not very readable. It’s why adding comments explaining what a given regex is checking is not the worst idea.

Specific business logic

Sometimes business requirements are tricky and not intuitive. Theoretically, the logic should be covered in some tech documentation but let’s be honest — no one likes reading tons of docs when need to fix one small thing. It’s why adding a short comment explaining the reasons behind some not obvious decisions may be OK. Just check if it’s a confusing logic that cannot be well explained in the code.

TODO comments

The developing process is split into steps. And it’s OK to not include all changes in one commit but leave them for the following ones. When your project is small and you don’t use any tool to track tasks (like Jira or Github Issues), having TODO comments saying what should be changed and where can be useful. Especially because code editors have special mechanisms to support them. The problem here is that this solution is not scaling and can be inefficient for big projects.

Tips on comments and avoiding them

Some tips may help you decide if comments are needed or how to use them correctly. First of all, before writing a comment thing if you can provide the same content in the code. Why do you need free text to express your intention? Why code cannot speak itself? Very often the need of writing a comment is just a symptom of a refactoring need. Also, if you have to write a comment (because of one of the reasons described in the previous section), keep a comment as close to the code which it describes as possible. If you add your thoughts at the beginning of the file, a person reading the code probably won’t notice it or not update it while implementing some changes. And talking about changes — don’t track them in the source code. Git is definitely a better place to track changes and their authors. Also, git (or any other versioning system) is your friend if you want to remove some functionality but have a chance to revert it. Don’t comment on the source code — create a commit with a meaningful name instead and programmers will find it in history if needed. Thanks to all of those tips your code will be cleaner, up-to-date, and more readable for everyone.

Summary

Of course, there are no strict rules about adding comments to the code. Each case is a little different and your role as a developer is to determine if comments can be useful in your case or distract/mislead the person who will read your code. I encourage you to think twice before you will add a new comment to your code and consider their props and cons. Remember: comments can lie — code never does!