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:

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.