Stories about Software


Comments: Here’s my Code and I’m Sorry

Heavily Commented Code: The Awful Empathy

Imagine a feeling–that empathy you get when you’re watching someone fail in front of an audience. Perhaps its a comedian relying on awful puns and props or a person in a public speaking course that just freezes after forgetting some lines. Ugh. It’s so awkward that it hurts. It’s almost like you’re up there with them. You start mumbling to yourself, “please, just be funny,” or, “please, just remember your lines.”

BanjoAccordionThe agony of sustained failure in such a situation doesn’t come on all at once. It creeps up on you in a crescendo of awful empathy and becomes memorable as it approaches the crest. But it starts subtly, before you realize it. There are warning signs that the train is unstable before it actually pops off of the rails. A classic warning sign is the “pre-excuse.”

Think of how you feel when someone gets up to talk at a meeting or give a presentation, and they start off with something like, “okay, this isn’t really finished, and Jones was supposed to help, but he got assigned to the Smith contract, and I did things in here that I’m not proud of, and…” With every clause that the speaker tacks onto the mounting lists of reasons that you’re going to hate it, you feel your discomfort mounting–so much so that you may even get preemptively angry or impatient because you know he’s going to bomb and you’re about to feel that tooth-grinding failure-empathy.

Okay. Now that the stage is set and we’re imagining the same feeling, know that this is how I feel when I open code file and see the green of comments (this is the color of comments in all my IDEs) prominently in a file. It’s as though the author of the code is on a stage in front of me, and he’s saying, “okay, so this is probably not very clear, and some of this is actually completely wrong, and changing this would be a nightmare, and you might want a beer or two, heh heh, but really, this will make more sense if you’re drunk, and, you know what, I’m sorry, really, really sorry because this is just, well, it’s just… it’s complete garbage. Sorry.”

That might seem a bit harsh, but think of what you’re looking at when you see code with a comment to actual code ratio approaching 1:1. You’re looking at a situation where someone needed to spend as much space and probably as much time trying to tell you what the code says as writing the code. Why would someone do that? Why would someone write a bunch of code and then write a bunch of English explaining to someone fluent in code what the code does? This is like me sending you an email in Spanish and putting the English equivalent after every sentence. I would do it if one of the two of us didn’t speak Spanish well or at all. And that’s how I feel when I see all those comments–either you don’t speak code very well or you think that I don’t speak code very well. The former occurs a lot with people who program haphazardly by coincidence. (“I better write this down in a comment because I had no idea that’s what an array was for. Who knew?”) The latter generates mind-numbing comments that rot. (“Declares an int called x and initializes it to 6.”) If you aren’t being forced to write comments by some kind of style policy and you’re not Zorro, you’re writing things in English because you’re not bothering to write and illuminate them in Code (I’m using the uppercase to distinguish simply writing some kind of compiling code from writing Code that communicates).

Self-Fulfilling Prophecy

There’s a substantial cross section of the developer world that thinks diligently commenting code is not only a best practice, but also table stakes for basic caring and being good at your craft. As I’ve previously explained, I used to be one of those people. I viewed writing comments in the same way that I view shutting drawers when I’m done using them or making my bed–just grunt work that’s unavoidable in life if you want to be a person that’s organized. Interestingly, I never really viewed them as particularly communicative, and, since adopting TDD and writing tiny methods, I viewed them largely as superfluous except for occasionally explaining some kind of political decision that transcended code (documenting APIs that you’ll release for public consumption are also an exception as this becomes part of your deliverable product). But I started to get increasingly disillusioned with the way comments would look in group code.

I would return to a method that I’d written six months earlier and for which I’d put a very clear doc comment, only to see something like this:

Holy crap! We’re clearly playing Russian Roulette here. Did the requirements change and we’re no longer endangering puppies? Is this code causing terrible things to happen? Who wrote that comment about 15? Hopefully not the same person that wrote the next line! And what should this code do–what the various comments say or what it actually does? Do the people responsible even work here anymore?

I’m pretty sure that anyone reading is chuckling and nodding sympathetically right now. You can only return to a method that you’ve written and see this sort of thing so many times before you come to a few conclusions:

  1. People almost never read your comments or any comments–they’re just a step above contract legalese as far as pointless noise in our lives goes.
  2. Even if someone does read your comments, they certainly won’t fix them along with the code they’re changing.
  3. On a long enough timeline, your comments will all become dirty, confusing lies.
  4. If you want to minimize the degree to which you’re a liar, minimize the comments that you write.

Surely this isn’t really news to anyone, and it’s probably answered with admonishments and mental notes to be more diligent about updating comments that everyone knows won’t actually happen. So why is it then considered good form and often mandated to put lies into source control for the later ‘benefit’ of others? Why do we do this, discounting the bed-making/diligence/good-citizen motivation?

To answer that question, think of the kind of code where you see comments and the kind of code where you don’t. If you see a four-line functional method with a single nested loop and no local variables, do you generally see comments in there? Probably not. How about a fifty line method with so many nested control structures that you need some kind of productivity add-in to know if you’re scoped inside that else you saw earlier or another if, or maybe a while loop? Bingo–that’s where comments go to hang out. Giant methods. Classes with lots of responsibilities and confusing internal state. Cryptically-named local variables. These things are all like cool, dank yards after a storm, sprouting explanatory comments like so many mushrooms. They sit there in mute testimony to the mildew-ridden, fungus-friendly conditions around them.

To put it another way, comments become necessary because the author isn’t speaking Code well and punts, using English instead of fixing the code to be clear and expressive. Thus the comments are compensation for a lack of clarity. But they’re more than that. They’re an implied apology for the code as well. They’re an apology for writing code and not Code. They’re an apology for the fact that writing code and not Code results in the project being a legacy project before it’s even done being written. They’re an implied apology for big, lumbering classes, winding methods, confusing state, and other obfuscations of intent. But most of all, they’re the preemptive, awkward-empathy-inducing, “hang onto your hat because what I’m doing here is actually nuts” pre-apologies/excuses to anyone with the misfortune of reading the code.

So please, I beg you–next time you find yourself thinking, “dude, nobody’s ever going figure this wackiness out unless I spend a few sentences explaining myself,” don’t bother with the explanation. Bother instead to correct the “nobody’s ever going to figure this out” part. Good Code speaks for itself so that you can focus on more important things.

Add a Comment

6 Comments on "Comments: Here’s my Code and I’m Sorry"

Notify of
Sort by:   newest | oldest | most voted
Andy Bailey
I hear you!! There is another, lesser known, aspect to comments in code which I have had actually seen but hope rarely happens. Scenario was Java code with file encoding of UTF-8 . An entry level programmer whose native language was russian actually put some TODO comments for himself, in russian, (project policy was that everything must be in English but noone told him). This exposed a nasty weakness in our nightly build/test system that expected everything in ISO-8859-1! How this managed to work for over 2 years without breaking was a mystery but it did. The build reports was… Read more »
Erik Dietrich

Wow — I consider myself fortunate not to have worked on a project where code comments were an integral part of the build process. You’re right. That adds a whole other, crazy dimension to the practice.


[…] method is actually doing. If I’m going to put my money where my mouth is in my various posts deriding comments, I need to do better when it comes to making code […]


[…] to codifying and mandating busy-work. I’ve made my evolving opinion of comments in code quite clear on a few occasions, and I consider them to be an excellent example. When you make “comment […]


[…] Comments: Here’s my code and I’m sorry […]


[…] blogged about a similar line of thought with code comments in the past. Comments in method bodies are basically developers saying, “I’m going to […]