Clean Code: Comments

I am always surprised that this subject is still debated today.

However, this discussion comes up regularly in talks with junior developers or even experienced developers.

I show here my practices on comments that I use for more than 10 years on a daily basis.

This article presents code examples in Java but the concepts apply to any language.

The majority of comments are redundant

Why write the same thing twice?

When you ask the question this way, the question is quickly answered!

However, it is still common to come across code like this:

We will notice in the previous example that the comments have no added value compared to the code.

From a reading point of view, your eyes have to focus on a lot more text than the same class without comments. We have to scroll constantly to read such classes. 

However, what’s the value of these comments? Nothing more than what is already expressed by the code.

To convince ourselves, let's read the same class without any comments:

Do you miss something?

As soon as the code is expressive, within the conventions, there is no need to comment on it. Instead, let's spend our time making the names of methods and parameters expressive.

Make your code expressive

In my carrer, I've seen developers spend quite a bit of time on comments. However, clear and well-designed code allows you to understand it just as well as with comments.

Take this example: 

Let's already note that the comments represent more text than the code itself.

Because we comment on the method, the parameter and the return at the same time, we quickly find ourselves rewriting the same things several times. We even look for other words so we don’t repeat ourselves.

The time wasted is significant. However, a simple renaming of the names allows us to understand everything without this comment!.

The same method with clearer names.

Certainly the length of the method name is substantial and may be surprising at first glance. However, it alone expresses the entire block of our previous comment.

Additionally, in places where it is called, one does not have to read the documentation. We read the code and we understand, what a lot of time saved.

Make your code expressive andain efficiency.

The code changes

Another negative point of comments is their maintenance. 

The code changes, often very quickly. Have the comments been maintained accordingly?

From my experience, I have never worked on heavily commented code where a method does something else than the comments!

Take this example: 

We now have a method whose comment claims to sort the values ​​in alphabetical order but the code does the opposite.

Who is right? The comment and therefore the method is bugged or the method and therefore the comment is wrong.

The time to read the comment, the method, to understand the inconsistency, to try to resolve this error, you could almost have coded a new feature of your application.

The code is the source of truth since it is the one that is executed. Let him tell us what he does. 

Comments are also sometimes a clue that shows us that the code needs a refactoring.

So we don't comment on anything anymore?

Let's not throw all the comments in the trash though.

There remain several cases, in my opinion, where the comments retain their interest.

Difficult to express the reason for a method 

Take this method for example: 

The name of the method is clear, as is its code. But why do we need it?

Why not put the single line of this method in the relevant place?

We can add a comment here to prevent future reviewers from asking these questions:

Which doesn't stop us from renaming our method:

The business is too complex to fit into a method name

Sometimes, our applications must respond to strange functional needs that are difficult to express other than through a comment.

You are coding a library or API

Some codes will be read by thousands of other people.

We must explain the use cases, exceptions, at best! Feel free to provide examples. In summary, make the reader of your comment happy to have read it.

For example :

Conclusion

Comments have an important role to play in our everyday code. But let's use them wisely. 

A good comment provides information about the code but we must, as much as possible, prioritize improving the code which is not intended to be a novel of comments.

This article can be summarized as follows: 

No comments	Comments
The comment uses the same words as the code	The business behind the method is very complex
The comment can be expressed by the code even if it means refactoring it	The method is a workaround of a bug or a technological choice
We no longer know if the comment is still relevant.	The method is part of an API/library