Comments: The Good, the Bad and the Ugly

TLDR: Effective code comments serve to elucidate the reasoning behind code design choices, rather than merely describing its functionality while avoiding redundancy and confusion. They should be concise yet informative, providing clarity for non-obvious code segments and explanations for unconventional approaches. Following established rules such as avoiding code duplication and ensuring comments do not obscure unclear code is essential.

This text is a resume of the Clean Code Chapter 4 - Comments, with some insights from me and other articles.

The Uncle Bob book helps you question your comments to understand if the comment is good or bad, and here you can find these questions more easily.

After some time reflecting on the comments, these questions become obvious practices that we internalize, becoming something natural. This kind of knowledge and evolution marks a significant milestone in a developer's growth, demonstrating more maturity and mastery over what they're doing.

Uncle Bob has a more purist view and describes comments as failures most of the time because they represent a failure on the part of the developer to create code that doesn't need explanation.

I don't believe comments are failures, but rather a tool that, when misused, can hinder more than help. As we'll see, some comments are extremely useful. However, to better understand what constitutes good comments, let's first look at what to avoid when we're creating comments.

Bad

Explaining the Code Itself

When you need to create a comment to explain what the code is doing, your comment is useless because anyone reading your code can already understand what it does. If your code is bad, and you need to explain, you should check the names of variables, functions, and the organization of the code itself. When the code uses variables and functions with explanatory names, following an organized structure, it is easy to understand what is being done.

TODO

Comments as "notes" of what needs to be done are comments that can be useful but should be avoided. You need to verify if this type of note is something that needs to be explicitly stated in the code if it is something that anyone will understand the need, and if you should not do this or if you cannot do it in this delivery One way to avoid the existence of TODO is to create an ESLint Rule.

Mumbling

Worse than an unnecessary comment is a comment that only makes sense to the author.

You can understand what is commented on, but it makes no sense to anyone other than the author. The comment needs to be easily understandable for other people.

Misleading

When you make a comment that contradicts your code, for example, when a function should return a boolean false, but in your comment, you say that the function returns a boolean true, or that the variables used are different from the ones that are truly used. This usually occurs when you try to explain the code that shouldn't need an explanation of what it does.

Mandated and Noise

When your comment has no value but is made out of a "need" to organize something that should not be described through the code.

These are comments that only create noise and their existence makes no difference. Comments that can be ignored; their existence can only cause some misunderstanding or error because to understand what the code does its existence is not necessary.

Journal, Atrributions and Bylines

The Developer should not describe how they reached the final product of their code, informing the journey they followed to reach that code is irrelevant to the code. Another problem is the comment made to inform who made this addition, something that is extremely unnecessary since we have version control tools that make it clear who modified where the code.

Position Markers

Some developers like to divide a file with one line per comment, just to separate what is being done.

This goes against the organization and clarity of the code, bringing only more pollution. If new features need to be created in the code, this comment will confuse instead of guiding other developers on the organization of the code.

Too Much Information

If there is too much information that should be described in the created code, this should be in the PR, not in the code. Including too much information, with all certainty, will add irrelevant information, the comment should be made with the necessary information, nothing more.

Good

This is a bit about comments that should be avoided, but now, we enter those that should be questioned to see if the comment is necessary.

Informative

Comments that provide necessary information that cannot be demonstrated through the code itself, such as the type of time formatting that is used.

Although the code explains what it does, the comment that shows time formatting is useful.

Clarification

When the code, even if well done, is still a bit obscure, or returns something that is too large or easily confused, it is also useful to create a comment that clarifies what the code does.

Warning of Consequences

It is also useful a comment that warns other developers of the consequences of that code, the problems it can generate, or that the change in it can generate changes in other parts of the code that are not evident in the code itself.

Amplifications

When you need to amplify the importance of something that is done by the code since the code itself cannot explain what is most important in it.

Using these tips to write code comments creates more readable and maintainable code. Helpful comments in your code enable other developers to more quickly understand the design of your codebase.