Minimise Code Comments

Photo by Luca Bravo on Unsplash

Code comments are problematic beasts. They can cause more problems than they solve. At first, they seem like the best thing since sliced bread. But with time, they decay and can become misleading. Therefore,

  The safest policy is to minimise the use of comments.

Consider comments a kind of failure. They are a failure on our part to express ourselves well in code. Given how expressive modern computer programming languages are, we have no excuse. 

Comments are a failure to express ourselves adequately in code.

Let’s go through two examples, remove comments and use the code alone to communicate intent.

First example:

  // check if customer has name
  if (!string.IsNullOrEmpty(customer.FirstName) && !string.IsNullOrEmpty(customer.LastName))

After refactoring, the code is so clear the comment is redundant:

if (customer.HasName)

Second example:

  if (customer.Id == null)
  {
     // Add a new customer to the database 

     /// ... lots of code adding the new customer to the database.
  }
  else
  {
     // Update the existing customer in the database. 

     /// ... lots of code updating an existing customer in the database.
  }

We could change to this listing that almost reads like English:

  if (customer.IsNew)
     AddNewCustomerToDatabase(customer);
  else
     UpdateExistingCustomerInDatabase(customer);

In this second example, we got two birds with one stone: 

1. We encapsulated the conditional predicate and conditional branches into helper subroutines. This action split the behaviour in the original code into more appropriate levels of abstraction: High-level policy for this code and lower-level detail in customer.IsNew, AddNewCustomerToDatabase() and UpdateExistingCustomerInDatabase(). The upshot: The code is more understandable and maintainable.
2. We removed the need for the comments by naming our helper methods to explain what they do.

At a previous company, some of us developers took the radical step of colouring our comments bright red. The idea behind this move was to have our code comments stick out like sore thumbs. They should be so annoying and in your face that the incentive to remove them becomes overwhelming. During my time there, the number of comments decreased sharply—the policy worked. More importantly, developers learned to express themselves clearly in code.

It is worth noting that there are going to be times when you have to use comments. Sometimes expressing certain concepts is going to be outside of the capability of our programming languages. In those rare cases where we have exhausted all opportunities of communicating in code alone, and our languages let us down, then use an explanatory comment. However, this is no time to let ourselves off the hook—using a comment should still feel dirty. 

When you do have to write a comment, make it the best one you could write. Hopefully, we can agree that we do not want to exacerbate one failure, that of needing to write a comment, with another one, that our explanation is unclear and verbose. Concision and clarity—that is what we should aim for in our code comments. 

To sum up, avoid comments wherever you can. Think long and hard about how you could express intent clearly in code. When you do have to write a comment, make it short and to the point.