Clean Code - Improve your code comments

Robert C. Martin, often called Uncle Bob, is an American software engineer well known for his books on Clean Code and Clean Architecture.

This article is one of a series that I am writing as an introduction to Clean Code. It’s made of notes that I wrote while watching a series of video lessons that Robert gave about clean code. This one will focus on tips about code comments, from the second episode.

You can find the 6 episodes' Youtube playlist here.

Code comments

What’s the purpose of a comment? The purpose of a comment is to explain the purpose of code if the code can’t explain its own purpose.

Code can explain its purpose by itself. But it did not used to be the case: Fortran for instance have only 6 chars names for variables.

Today's languages are remarkably rich: we can have very long names, we have structs, classes, namespaces, etc. We have all the tools that we need to write code that explains itself.

Not all comments are bad

Nothing can be quite so helpful as a good comment.

Nothing can be quite so obscuring as a bad comment.

→ Comments are not “pure good”

Every comment you write is a failure

The proper use of comments is to compensate for our failure to express ourselves in code. And then because we technically can express ourselves in code, we don’t need comments.

Every use of a comment represents a failure. So don’t comment first, try everything else then comment as a last resort.

→ When you write bad code, don’t comment it, clean it.

The right colour of comments

Comments lie. Not intentionally, but as the code change, most of the time they don’t, because they are often ignored, and no one maintains them.

Comments are often in a soft and invisible colour. Change IDE settings to paint comments in bright red, so that they will be very visible. Also, this being quite ugly, it may help you to avoid writing useless comments.

→ Change IDE settings to paint comments in bright red.

Examples of bad comments

• Comments that explain complex conditions or loop statements. Instead, use explanatory variables.
  
  Read more about explanatory variables in the previous article.

• Comments that reference code elsewhere (ex: \\ at this moment, {other code} should have been called).

• Redundant comments that takes more time to read than time to understand the code itself.

• Noise comments. For instance, comments explaining stuff that developers already know, or comments that have been copy-pasted with mistakes.

• Mandatory comments. When you force developers to write comments you get stupid and useless comments. For instance, documentation comments that list all parameters of a function. Documentation tools are already smart enough to do that.

Examples of acceptable comments

• Copyrights or Legal boilerplate code.

• When a name is not clear but it’s named on purpose (ex: when using a design pattern or a framework), you can comment to give more context.

• Informative comment: date format, regular expression, etc. But this is a double edge knife: this is very helpful while you update the comment when the code change (if not, the comment will be lying).

• Warning of consequences: a function that takes time to run, or that is not thread-safe, etc.

• TODO comments: a TODO means “don’t do”. You can write TODO comments but don’t commit them to Git: they have to be done. If not, they will become “don’t do” comments. A much better option if you can’t do a thing now, is to use the ticket system of your project (Jira, Notion, Trello, …) and create a technical task.

• Amplification: when something is clear enough but it needs to stand out.

• Documentation markups ONLY if made for external APIs. It’s acceptable for public things that are gonna be exposed to external developers. If you’re writing code that only the team is gonna see, you don't need comments, because the team knows the system.

• Commented out code. If a code is not needed, remove it. You can comment code while working on something, but don’t commit it to Git. And if you are scared to lose some code, don't forget that it will stay in the Git history.

Wrap up

Here were my few notes on writing good comments from Uncle Bob’s lesson on Clean Code.

You can find my other notes on the next lessons here:

• Lesson 1: What is Clean Code?

• Lesson 2: Function and variable names.

I hope this article has been helpful to you. If you have any questions or feedback about this article, don’t hesitate to contact me on Twitter!