Clean Code Series #4 - Comments

Part 4 - Comments

Are the comments necessary? In this chapter of the book Clean Code: A Handbook of Agile Software Craftsmanship, they are some interesting concepts that we should consider when we think about adding comments to your code.

The Purpose of the Comment

The purpose of the comment is to explain the purpose of some code when the code can't explain this purpose by itself. Basically, it's considered compensation by the failure to express yourself in the code. Comments are considered failures by Uncle Bob, in the sense that you didn't have the capacity to produce an auto-explained code.

Comments have a tendency to rotting during the time. It's not common to waste time "refactoring a comment" despite the code. Time is money, and time wasted producing useless comments as a waste of money. As simple as that.

Look at this example:

It's pretty clear that the code is not explaining its intent. The fix for this scenario is simple (just a matter of creating a function that can explain the intent of this validation):

So, avoid the comments as much as you can. Comments should be the last resort after you tried everything. When you write a bad code don't comment on it, but clean it!

Acceptable Comments

They are some scenarios where you can add comments:

- Informative comments: look to this next example:

Understand the intent of a regular expression is a challenge for many of us. However, even in this case, it's possible to create a class that can encapsulate the intent of this code in a specific function. The code again turns into the source of truth (as it must be).

- Warning for consequences: the strategy is to alert about some consequences of some specific part of the code:

They are better ways to solve overcome this code but it's acceptable and useful this kind of comment.

Bad Comments

- TODO Comments: this is the type of comment that Uncle Bob calls as Don't Do Comments. You will basically left it there and nobody will work on this. If there is a necessity to add a TODO, that means the code is not right. Eliminate them as much as possible, trying to write better codes in order to avoid the TODO's.

- Mumbling Comments: when you have the necessity to add some comment just because the process require it. If you need to write this type of comment, make sure you will write with quality.

- Redundant Comments: look at this code:

There is no reason why you should write a comment that describes exactly what it's explained in a clearly way in the code. You are not adding any more information to this part of code.

- Mislead Comments: when a comment is not precise enough, leading you to a different path the code is supposed to do. As an example, consider the format using Regular Expression. If the code is changed for some reason, you can incur in a problem if the comment is not updated properly, leading the next reader to have the false impression the code is formatting in a way.

- Journal Comments: commonly used in the past, the journal comments are like a history added on the header of the file:

We do have source control tools to work out with this kind of history. This approach just cause more unnecessary work.

- Auto-Explained Bad Comments

These are some examples of non-necessary comments:

Commented-Out Code

Last but not least, one of the worst practices ever is comment-out the source code. If the code is commented, it's useless. You must trust in you version control to maintain this historical code, in the case you want/need to implement further in the code. But you should take it out from the code, instead of maintaining this part commented-out.

I hope you have enjoyed this step. Bellow the list of the other chapters: