Don’t for a minute misinterpret the title of my column, and think that I’m going to decline to comment on something. Ha! What sort of a pontification would that be?
No, I’m going to hold forth on a topic that’s been bothering me for some time. And that topic is source code without comments.
I never would have guessed that I would encounter this problem. Well, not counting first year CS students who think they know better or long-experienced EEs who view writing a test driver as the last annoying step on the very long road to building some sort of “interesting” device. Those folks never write comments. And that’s fine, because nobody cares about the code they’ve written anyhow – usually not even them.
But, in terms of the rest of the world? I figured that putting comments in source code was the sort of common sense thing that everyone does. Sort of like taking the keys out of your car when you park it. Or wearing a high-visibility color when talking through the woods during hunting season.
Apparently, I was mistaken. There appears to be a growing trend toward people writing code with zero – or at least darn close to zero – comments. And I find this trend to be very alarming.
Early in my professional career, the importance of comments was drilled into me in a most serious way. Back then, we wrote operating systems in assembler language, and woe unto the poor fool that didn’t provide one intelligent comment per line of code. Of course, comments that described the instruction in English were worse than no comments at all. For example (expressed in x86 assembler for your convenience):
mov AX,05 ; put a 5 in AX
dec DX ; subtract 1 from DX
jnz foo ; if not zero, jump
Yeah… comments like these got you well and truly abused. Remember, this was before everyone had to attend “valuing difference” training. Back then, having your dev lead say that your code was “some of the worst shit” he’s ever seen was an almost everyday occurrence for some folks. They either learned how to write good code with good comments or moved on to a job in marketing.
Apparently, times have changed.
Just as I did back then, today I firmly believe that source code without comments is sloppy and amateurish. So, I’ve been struggling to understand why writing intelligent source code comments has started to become optional for some very good engineers.
I lay the blame for much of this trend at the feet of the open source software (OSS) movement. Of course, you might correctly argue that I blame most of what is wrong with the world (hunger, war, pestilence, the declining quality of Law & Order: SVU episodes) on OSS in general, and on Linux in particular. But, in this case, I think I might be on to something. Most OSS projects were historically developed by one or two folks who were sure they knew what they were doing while creating their software for “sport.” Their attitude was commonly “this software works for me, if it works for you or you can reuse some of it for something else, that’s good too.” The “niceties” of software engineering practice were often irrelevant or escaped their notice. What was important was they had written some code that filled a need, and that they contributed this code to the community freely. However the result was often code with no comments, and using 1 and 2 letter variable names.
Fast forward to the 21st century, and we now have a vast base of code that looks like it was written by a secondary school student while on summer holiday. In fairness, while the Linux kernel isn’t nearly as gross as it once was – I was shocked to discover that it actually has some useful comments and variable names longer than 2 letters – much of it is still not what I would call “great code.” And this (OSS code in general and Linux in particular) is the code to which CS students are exposed as they learn their craft. It’s no wonder they grow up thinking that “b” is a perfectly good name for a variable that contains a buffer pointer.
As if that’s not enough, I suspect that globalization also plays a part in the lack of source code comments in new modules. If you’re a non-native English speaker I would guess that writing comments in English could pose a significant challenge. And if you’re on a team with members in, for example, China, Russia, and the US, using English for comments is probably the only reasonable alternative. Putting comments in Chinese (assuming the compiler will accept Unicode source code files… does it?) might be relatively easy for you and might even help your immediate colleagues, but it’s probably not going to do much for the team members in Russia. Thus, new source code written by highly geographically dispersed teams often remains uncommented or is only sparsely commented. While the reason might be understandable, it’s still sad. I suspect that even a native speaker of Latvian who is asked to maintain this code in the future would prefer to have at least some intelligent English language comments to no comments at all.
Why all the fuss? Why do we write source code comments, anyways? Well, boys and girls, let’s start at the beginning. We write source code comments for the sole purpose of making the maintenance of our code easier. Period. Full stop.
Of course, “making maintenance easier” encompasses a vast number of things. The most important thing that it includes is the category of comments that describe what it is that you’re trying to accomplish. In a device driver, this includes little trivialities such as how you talk to you device and how you expect it to talk back to you. And this is the reason that renders moot the (stupid) argument that you hear from some C Language programmers that their code is “self documenting.” I’ve yet to see any C code that describes how a given register set is used to make a device function.
“Making maintenance easier” also encompasses little things like describing the data structures and algorithms you use. Sure, somebody can sit down with a piece of paper and figure it out based on the code you write. But, since you’re writing the code and you (presumably) understand it already, why not save those who come after you some time and explain it to them? “Making maintenance easier” also encompasses describing any built-in assumptions and limitations of those structures and algorithms. But, of course, you’ve ASSERTed those and made them clear in your SAL notations anyhow, right?
While the discipline to write intelligent source code probably sounds very altruistic (wanting to help future maintainers of code that I write) I have to admit that the main reason I write detailed comments isn’t really all that noble. In fact, the real reason that I write comments is to help myself. Detailed comments save me a ton of time when I look back on my old code and try to figure out what I was doing. What’s funny is that “old code” in this case could be code I’ve written only a few days before. Without comments, I sometimes look at the code and think “Hmmm… Did I write this? I wonder what I did.”
So, whether you do it for your team members, for maintainers that come after you, or just to save yourself the embarrassment of not remembering how your own code works, please do write source code comments. If you’re not a native English language speaker, I’m sorry. I know this is an additional burden. But it’s something that really needs to be done. If you’re a lead or a manager (do dev managers actually read this stuff? No chance), make intelligent comments a requirement. Suggest that code without intelligent comments is some of the worst shit you’ve ever seen (just be sure to do so a respectful and politically correct manner). And be sure to give your devs sufficient time to write those comments, OK? Ease up on the lash a bit, boss man.
Let’s see if we can stop this trend before it becomes any more widespread.
Peter Pontificates is a regular opinion column by OSR consulting partner, Peter Viscarola. Peter doesn’t care if you agree or disagree, but you do have the opportunity to see your comments or a rebuttal in a future issue. Send your own comments, rants, or distortions of fact to: PeterPont@osr.com.
OSR Open Systems Resources, Inc.