Stories about Software


Is There a Correct Way to Comment Your Code?

Editorial note: I originally wrote this post for the NDepend blog.  You can check out the original here, at their site.  While you’re there, take a look at all of the visualizations and metrics that you can get about your codebase.

Given that I both consult and do a number of public things (like blogging), I field a lot of questions.  As a result, the subject of code comments comes up from time to time.  I’ll offer my take on the correct way to comment code.  But remember that I am a consultant, so I always have a knee-jerk response to say that it depends.

Before we get to my take, though, let’s go watch programmers do what we love to do on subjects like this: argue angrily.  On the subject of comments, programmers seem to fall roughly into two camps.  These include the “clean code needs no comments” camp and the “professionalism means commenting” camp.  To wit:

Chances are, if you need to comment then something needs to be refactored. If that which needs to be refactored is not under your control then the comment is warranted.

And then, on the other side:

If you’re seriously questioning the value of writing comments, then I’d have to include you in the group of “junior programmers,” too.  Comments are absolutely crucial.

Things would probably go downhill from there fast, except that people curate Stack Overflow against overt squabbling.

Splitting the Difference on Commenting

Whenever two sides entrench on a matter, diplomats of the community seek to find common ground.  When it comes to code comments, this generally takes the form of adages about expressing the why in comments.  For example, consider this pithy rule of thumb from the Stack Overflow thread.

Good programmers comment their code.

Great programmers tell you why a particular implementation was chosen.

Master programmers tell you why other implementations were not chosen.

Jeff Atwood has addressed this subject a few different times.

When you’ve rewritten, refactored, and rearchitected your code a dozen times to make it easy for your fellow developers to read and understand — when you can’t possibly imagine any conceivable way your code could be changed to become more straightforward and obvious — then, and only then, should you feel compelled to add a comment explaining what your code does.

Junior developers rely on comments to tell the story when they should be relying on the code to tell the story.

And so, as with any middle ground compromise, both entrenched sides have something to like (and hate).  Thus, you might say that whatever consensus exists among programmers, it leans toward a “correct way” that involves commenting about why.

Read More


Ghost Doc Says the Damndest Things

Editorial Note: I originally wrote this post for the SubMain blog.  You can check out the original here, at their site.  While you’re there, have a look at GhostDoc, which can help both with code comment maintenance and the generation of help documentation.

Some years ago, I was doing work for some client or another.  Honestly, I have no recollections of specifics with the exception of a preference for exhaustive commenting.  Every class, every method, every property, and every field.

Of course, I didn’t learn this at first.  I didn’t even learn it in a reasonable time frame.  Instead, I learned it close to handover time.  And so things got a little desperate.

Enter GhostDoc, My Salvation

Now, depending on your perspective, you might scold me for not diligently commenting all along.  I will offer the explanation that the code had no public component and no intended APIs or extensions.  It also required no “why” types of explanations; this was simple stuff.

The client cited policy.  “We comment everything, and we’re taking over this code, so we want you to do the same.”  Okie dokie.

Now, I knew that in a world of code generation and T4 templates, someone must have invented a tool that would generate some sort of comments or another.  At the time, a quick Google search brought me to a saving grace: the free tool GhostDoc.

While it did not allow me to carpet bomb my code with comments in a single click (and understandably so), it did allow me to do it for entire files at a time.  Good enough.  I paid my non-commenting penance by spending an hour or so commenting this way.

And do you know what?  It generated pretty respectable comments.  I recall feeling impressed because I expected empty template comments.  Instead, GhostDoc figured out how to string some verbs and nouns together.

Read More


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.