Why You Should Limit Your Use of Comments to Make Clean Code as a Developer

I used to think that clean code involved adding a lot of detailed comments.

After reading Robert C. Martin’s book titled Clean Code, I realised I was using comments in the wrong way.

Here are the reasons why:

Limit your use of comments, explain yourself in code instead

Comments tell lies, code does not.

Comments are used to explain what the code does, but if they are not used correctly, they can spread misinformation about the code. Here’s how:

1. Bad explanations — The comment does not explain what the code does. Confusing the reader, and making them interpret the code for something else.
2. Time — When you first write a function, you put a comment to state exactly what the function does. If the codes functionality changes, the likely scenario is the comment never gets updated. Meaning the comment is now a lie.

Code does exactly what it says. Code may be hard to interpret, but it never lies.

That’s why it is vital to use good naming conventions and formatting, to make code easy to read and interpret.

Look at the following examples:

Bad Code:

//Function receives a list of albums and an artist. It then loops through the list of albums and returns a list of albums which have the same artistprivate function loopFunction($items, $artist)
{
    $artists = [];
      foreach($items as $item){
          if($item['artist'] === $artist) {
              array_push($artists, $artist);
          }
      }
      return $artists;
}

As you can see the code is vague through bad naming conventions, no type declaration or return type specification. Therefore a comment needs to be added to explain it.

Better Code:

private function findAllAlbumsFromArtist(array $arrayOfAlbums, string $artist): array
{
    $arrayOfAlbumsFromArtist = [];
    foreach($arrayOfAlbums as $album){
        if($album['artist'] === $artist) {
            array_push($arrayOfAlbumsFromArtist, $artist);
        }
    }
    return $arrayOfAlbumsFromArtist;
}

Did this function need a comment, or do you understand what it’s doing?

Clear code needs no explanation, bad code does.

So when you next go to write a comment, ask yourself: Am I writing this comment because my code is not clear?

So when is there a need for comments?

1. Explaining intent behind the code

You may have coded something in an unusual way for a reason.

If that is the case, it is fine to explain your intent behind the coding decision with a comment.

This is only acceptable when you have no choice but to code in this way.

2. Making code clear

Sometimes code cannot be made readable.

There is just no way to provide context through naming conventions which is understandable to a new reader. If this is the case, leave a comment explaining exactly what the code does.

But make sure to update the comment when you make a change, and to state exactly what the code does.

3. Expressing the importance of an area of code

To readers, it can be difficult to understand which part of the code is important.

This is where it can be useful to leave a comment explaining the importance of this code.

//This trim function is really important, it ensures there are no spaces within the url

4. Explaining consequences of code

Help your teammates out by explaining the consequences of running certain code:

//Beware: This script takes 5 hours to run

Focus on writing good code and the amount of comments you need will reduce

Less is more.

A well-placed comment can help fill the gaps of knowledge. But next time you go to put a comment in your code, spend a few minutes to decide if this comment is needed. If so, make sure it’s accurate and descriptive enough for a first-time reader to understand.

Most of the time, your time is better spent making your code more readable.