How I Learned to Write Comments

Here's how it happened. Before I joined, the company had produced a first version of a piece of software, tried it out, and found that although the ideas were good, the user interface was inadequate in a way that couldn't be fixed without a major rewrite. So, there needed to be a second version, and that's what I was assigned to work on when I joined. There were already two other people on the project, nailing down the user interface design and taking care of other management issues. The plan was, they'd finish doing that, I'd work out a new internal structure, and then we'd all sit down and crank out the code. And, that's exactly how it went … one of the few times in my experience that a large-ish project has gone as planned. (We also had an advisor who was very helpful.)

What do comments have to do with that? Well, to work out the new structure for the second version, the first thing I needed to do was understand how the first version worked so that I could preserve all the good parts. However, there wasn't any separate documentation for the first version, and the programmer who had written most of it had left, so the only way to understand it was to read through the code.

And, that wasn't easy! For one thing, the code had basically no comments. For another, a lot of the variable names were short and uninformative. If I remember correctly, part of the problem was that the names used Hungarian notation (which actually might have been helpful if I'd understood it) and part was that the programmer's choice of names had been influenced by vis native language: Chinese. So, mostly I had to ignore the names and just look at the actual function of the code.

Even that wasn't easy … there were some weird design decisions that threw me off, and also a few bugs that I had to recognize and leave out. But, in the end I did manage to make sense of everything, so probably the code wasn't quite as cryptic as I make it out to be.

Anyway, the important thing is, as I read through the code and figured out what each function did and what each class was for, I had all these little moments of insight. Oh, that's how that works! Oh, that's why that's divided up in that way! And, along with the insights I had another thought, over and over: why didn't ve just say so?! A few sentences here and there to give overviews and explain non-obvious details would have saved me a tremendous amount of time. Ever since then, I've included those kinds of comments in my own code.

(I also became very finicky about class, function, and variable names, wanting them to have exactly the right meanings, but that's another story for another time.)

When I say I've included those kinds of comments in my own code, is that really true? Does it make a difference if the program is small? Well, yes … for a really small and casual program I might skip the comments. You probably know the kind I mean: a single file, a function or two, something that computes compound interest or tests whether a number is prime. But, for anything larger than that I'll probably want to write something.

Does it make a difference if nobody will ever see the code but me? Not really. If a program is large enough to require comments, I'll probably come back to it some day and not remember how it works, and then I'll be glad I wrote some nice comments. In other words, comments are useful not just to other people but also to future versions of myself. (Or, maybe the future versions of myself are other people!)

Come to think of it, comments are useful to me in the present, too. Writing comments clarifies my thinking in much the same way that writing essays does (see Advancement). In fact, when faced with a difficult piece of code, I'll often write the comments first, as a way of planning out what I'm going to do. That makes a lot more sense to me than having separate design notes that nobody ever looks at!

So, anyway, that's the story of how I learned to write comments.

To put it another way, what I've been talking about so far is not so much a “how” as a “why”. Why do I write comments? Because I've seen firsthand what they're good for. I've had to read code that didn't have them, and been irritated, and I've read code that did have them, and been glad they were there.

Now, to finish up, I'd like to say a few words about the “how” form of that question. How do I write comments? Or, rather, how should anyone write comments? What's the best way? That's a big question, of course, and a misleading one, since there's no single answer. What's the best way to write code? To write essays? What's the most effective way to communicate? Nevertheless, I'd like to offer a few humble suggestions.

• Although I'm obviously biased here, I really do think that reading a bunch of poorly-commented code is a good way to get a feel for what kinds of comments are useful. Reading code is also a good way to get ideas about programming in general, as long as you remember that not all ideas are good ideas.
• As I mentioned earlier, I think the main things you want to try to do with comments are give overviews and explain non-obvious details.
• Don't be shy about writing long comments when necessary. For me, even a simple point often takes two or three lines, while a high-level explanation can sometimes take a whole page.
• On the other hand, don't feel obliged to write comments when you don't have anything to say. If, for example, you have a function drawLine that takes arguments x1, y1, x2, and y2, I'd call that done. Explaining that x1 is the first point's x coordinate is just going to teach people to ignore your stupid comments.
• I find it very helpful to organize my code into sections. If the text editor that you're using has some special section marker that it recognizes, you'll probably want to use that; if not, well, a comment line full of dashes or slashes or whatever will do just fine. You can also include a section title in the line, like so, or have two lines with the title in between.

  --- constants ---

• When you want to put the same comment in more than one place, sometimes that's a sign that you ought to refactor to bring the places together. Sometimes, though, it's a genuine problem. The best solution I've found so far is to use a unique string as kind of a footnote marker to link the various places. So, in one place I'll have the marker plus the entire comment, while in the other places I'll have just the marker. My current favorite marker is (*), which can be followed by (**), (*3), and so on if I happen to need more than one marker in the same file.