Some comments about comments

posted: November 29, 2018

tl;dr: Be kind to your future self and others by writing some comments...

I’ve never believed in 100% self-documenting code. Instead I think of self-documenting code as an admirable goal, but something that, like the pot of gold at the end of the rainbow, is unattainable. Certainly it is of great help to choose descriptive names for variables, functions, classes, and methods, and I’m a huge advocate of writing elegantly simple code that has readability as its primary characteristic. However comments do have their benefits, and those programmers who leave them out handicap future developers who must maintain the codebase, often including themselves.

The number one knock on comments, from those who avoid and/or abhor them, is that they can fall out of date with the code, which after all governs the actual behavior of the system, and therefore can be potentially misleading. This certainly is true, but it is also true of any documentation not automatically generated from the code, such as readme files in a version control system, user documentation on a website, tutorials, courses, books, and even how-to blog posts (but not this one 😉).

I could cite multiple examples just in the past week where I ran across documentation that had small errors in it. I was still glad I had read the documentation. Older technical books that are a few versions behind the latest release of a software system can still be valuable. Certainly if everything were 100% up-to-date and accurate all possible misdirections would be eliminated. On balance it is far more beneficial to have documentation and comments than to have nothing but the code itself.

Comments only matter to humans; there are reasons most languages have them

The other complaint about comments is that it takes time to write them. That is true, and a balance needs to be struck between writing too few and too many. Some general guidelines that I like to follow are:

Explain why. The code itself can usually answer the question of what or how something is being done, except in the case of cryptic code, but it usually cannot answer the question of why it is being done. Why is a list being sorted at potentially high cost, if it is not obvious? Why are certain operations ordered in a particular sequence?
Explain what is being done, for cryptic or complicated code. For example regex is by definition cryptic, so put a comment before the regex explaining what the regex is supposed to do.
Explain the purpose of non-trivial functions, methods, and classes: a well-chosen name can’t explain everything, and it’s helpful to future readers to have an interim explanation between the name and the lines of code themselves.
A short one-line comment can help explain the purpose of a 5-to-20 line block of code, without having to break it out into a function just to give it a descriptive name.
Once code is in production, put in a comment for each bug fix. The comment should reference the ticket number for the issue. Whether it is because of an unclear requirement or an error in the code itself, a mistake crept into production. A comment can help prevent that mistake from ever returning if someone else changes the code back to its original state or is wondering why, when reviewing the change history, the code was modified.

My number one guideline, however, is to put in enough comments to explain the code such that if I myself have to return to it six months or more in the future, I will be able to figure out what is going on in the code and how to fix or change it. Six months is usually long enough for me to forget most of the nitty-gritty details; as some have remarked, code you wrote six months ago might as well have been written by someone else. Be kind to your future self: put in comments so that you and others can more easily understand the code in the future.

I’ve seen others struggle with this. Recently I worked with an idealistic developer who was just entering the profession. He thought the code he was writing was intuitively obvious, at least to himself; he also didn’t welcome feedback from others. He had heard of the self-documenting code ideal, and felt that he was achieving it, so he didn’t put in any comments. His code got into production, more than six months went by, and then he was asked to make some feature additions to it.

He ended up literally cursing his former self as he tried to decipher the code he himself had written. He ultimately declared it incomprehensible and did a major rewrite and refactoring. That’s a bit of an extreme example, as the original code was indeed overly complex. It does, however, illustrate the value that comments provide.