Comments Rot

Photo by FOODISM360 on Unsplash

Previously we discovered that it’s a good idea to minimise the use of code comments. Explaining software behaviour can often be achieved more effectively by our expressive modern programming languages, making many comments irrelevant and replaceable. Frequently code comments add to the noise and not the signal.

Unfortunately, it gets worse: Comments can cause serious confusion as the code around them changes.

To illustrate, check out this redundant comment: 

  // check if customer is archived
  if (customer.IsArchived)

The comment is harmless noise. Or is it?

After some time, the comment is unchanged, but the conditional looks different:

  // check if customer is archived
  if (client.IsDeleted)

Code and comment appear to be at odds. Questions forming in the mind of a maintenance developer might be:

• Are deletion and archiving two words for the same thing?
• Is a client the same concept as a customer?
• If not, what is the difference between them?

Since the code is not clear, the developer would need to talk to someone, review the system documentation, look at source control history, or delve deeper into the program to work out what is going on. 

The comment has stopped being helpful and has become a hindrance.

After a few more weeks or months, the code has changed even more, yet the comment remains the same:

  // check if customer is archived
  client.Apply(modifications);

The comment is cryptic and confusing: What is its relevance with regards to the code? Where is the check whether we’ve got an archived customer? The code seems to be doing something entirely different. Should that check be there?

As a maintenance programmer who is not familiar with the code, it can be frustrating to encounter misleading comments.

The reality is that we developers forget to update comments. It is better not to have a comment than have one that is incorrect – one that has decayed to misinformation.

Comments are good for explaining code. Unfortunately, they create a synchronisation problem: As developers make changes, existing comments may end up out of context and become a source of confusion. 

Please be aware that comments rot over time.