SOMH #3 - Ode to No Comments

This essay is part of the series "Strong Opinions, Moderately Held", an indefinite journey into thoughts, ideas, and convictions regarding a plethora of subjects.

The phrase "no comments" is not only uttered by the obviously guilty under a barrage of questions from reporters, but also by many developers and even some bloggers too. And I'm guilty as charged when it comes to disdaining comments in code as well as the typical comments on articles. Do note that there are exceptions, but in general I find code comments having the following unfortunate traits.

Comments are too short to convey proper meaning and nuance.
Comments are too detached not to drift and lie.
Comments are too easy to write.

Let's go through them one at a time.

Too short to convey proper meaning and nuance

Similar to what I wrote in SOMH #1, capturing meaning in a sentence or two is hard. This is aggravated in code as the vast majority of code comments aren't even a sentence but rather a sentence fragment. Ever seen something like Timing issue fix or API workaround? There's no meat there, very little explanation of the what, and certainly no explanation of the why.

True, true, there are ways to mitigate this. Perhaps referencing an issue or a ticket number, but that is a band-aid and a poor one at that as it involves a context switch in the hope of discerning the reason for that comment's existence. If you on the other hand strike out to write a multi-line, eloquent comment you're already on your way to a solution to the next problem.

Too detached not to drift and lie

There is nothing inherently connecting a comment to that which it comments. Implementations change and are replaced, but often there are ancient comments still lurking, muddying the waters. Fragments of a code base past that no longer retains what meager meaning they once did. It's easy enough to automate the warning and removal of unused variables and functions, but there are very few tools if any that can do the same with comments. Once added to the code, the onerous of keeping them relevant is fully on the developers. Woe betide the one inheriting a code base full of comments for they shall weep thrice; once for decrypting the actual code, once for decrypting the comments, and once more for vainly connecting the two.

Now, there are some ways to mitigate this shortcoming in code; chief among them doctests and other forms of literate programming. By coupling the comment to the code, the chance of avoiding drift is reduced as it likely will result in a failing test.

Too easy to write

Code comments are painfully easy to write. It can be so much easier to just write a comment as it allows you to retain poor naming, avoid refactoring, skip extracting functions and methods, and generally not consider if there is a way for your code to tell a story of its own without having to read a meta-story, i.e. said comments.

Imagine if comments came at a higher cost compared to performing those other actions. Actually, it usually does, as those other motions will make your code more malleable and understandable. A comment might only aid with the latter, and only at the very best of times. It will hardly ever be more than a bandage feebly covering the lacking code quality. By avoiding them, we can focus on putting in the work required to raise the quality of our code.

How does this relate to an article's comments? You may have noticed that there is no comment section on this blog. You may also have gathered by now that this is quite intentional. My reasoning is that if you're inclined enough to engage in commentary, at least be prepared to put a little effort into it. If any of these SOMH pieces rubs you the wrong the way, I'd be more than pleased to see a written piece on your blog that addresses what peeves you and why. By raising the threshold to commenting a few centimeters above that of the typically flame warrior-littered comment sections, we just might raise the level of discourse as well.

And if at all possible, always opt to use a means of communication with higher bandwidth than mere written words.