About This Site
Concepts for Persistent Objects
Language Design Principles
An Owning Pointer
Finalization in Java
What Is Lambda?
How I Learned to Write CommentsWhen I started programming professionally, I didn't understand about comments. I mean, I knew what they were, but I thought they were stupid; I didn't understand why anyone would ever want to use them. And, if anyone had told me I had to, or tried to convince me I ought to, I'm sure I would have been terribly stubborn about it. It was fortunate, then, that the very first task I was assigned had the side effect of making the point of comments perfectly clear to me.
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.
@ November (2008)