Comments Rarely Improve Your Code

The debate over comments in code is ongoing. At least once per year for the last 30 years, I’ve been involved in a discussion on the subject - often accidentally and reluctantly. To be honest, my perspective has changed over time. I used to comment every method, I used to comment any line of code that was “weird”, and I used to comment any blocks of code that were too complicated. Today, I rarely comment, if ever. Over time, I’ve come to realize that most comments are unnecessary.

Most of the comments I see fall into one of a few categories:

• Documentation - structured documentation of the code, ideally used for automated creation of a reference manual
• Explanation - describes what the code block does
• Frustration - expression of dissatisfaction with the code or the circumstances
• Jollification - a joke

Of these, documentation and explanation might improve the code, but often do not. Frustration and jollification do not improve the code.

Documentation is structured comments, often at the declaration of a function or method that describe what the code does and the expected inputs/outputs. These comments are not intended to improve the code itself. They are intended to document the code. Ideally, these comments are swept by some third-party tool and used to generate a reference manual. In well written source code, most, if not all of this information, should be readily gleaned from the declaration itself.

A well named method will indicate what behavior it provides in the name. Well named, well formed parameters and return types will further indicate what the method does. The comment, at that point, is superfluous, save the external documentation that gets generated.

Explanation is comments that describe what the code does or perhaps explain some reasoning for why the code is the way that it is. The primary differences between documentation and explanation are structure and placement. Explanation comments can appear anywhere in the code. They might explain an entire method or a single line of a method. They are often unnecessary and, interestingly enough, give us a clue as to how the code might be more clearly written.

Here is a function call with a comment:

// Determine if item can be purchased with credit remaining
Boolean allowed = checkItem(Int id, Float amount)

The comment tells us how the code could be more clearly written:

Boolean isCreditPurchasable = canBuyItemWithCreditRemaining(Item item, Float creditRemaining)

If you find an explanation comment over a block of code, this is likely an indication that the block can be extracted into a function with a descriptive name. If the block does many things, then perhaps the components can be extracted into functions each representing a discrete step.

Frustration and Jollification are low utility for the reader. They may feel good to the author at the time and might offer a laugh or sense of empathy to the reader, but they do nothing to improve the code itself.

Now, somebody is going to make the argument that it is necessary to comment some code; that there are circumstances outside of the code itself that would in no other way be evident. Sure. Maybe. That happens on rare occasion, which is why I indicate documentation and explanation might improve the code.

Comment it if you can’t think of a way to clearly express it in the code itself.

Previously published at https://docondev.com/blog/2020/5/1/comments-rarely-improve-code