Bremsstrahlung

One thing that every introductory programming book and every Computer Science professor will exhort programmers to do is comment their code. And indeed, it makes sense; write down in plain English what you're code should do and how it does it so that you or anyone else can understand it easily. The trouble is, quite often people never get around to putting in comments. Why?

Well, first of all, it's usually fairly boring. If you already know what the code does, it's not too exciting to spend time going through and writing explanations. And especially before the code is done, what one probably really wants to be doing is writing the code, not writing about how one is going to write the code.

However, there's a worse problem, which in my experience is the one that really accounts for lack of comments: To write comments, you have to know how the system works. Although this sounds easy, the problem is that often times the programmer doesn't know all of how the code does or will work until it's totally done and tested. I usually start each programming task with a pretty clear idea of the algorithm I'm going to implement and what functions and variables I'll use to do it. But then, in most cases I find that as I test it, there are a few details that I hadn't fully anticipated, either there's some way I could make the code more efficient and elegant, or there's some case that I forgot to take into account. I then end up restructuring code, sometimes drastically, and the end product often looks totally different, with whole swaths of functions and variable which have been replaced. Since this generally invalidates any comments that I wrote (or could have written) before, I've generally gotten in the habit of assuming that there's no point in writing comments as I go along.

There are a couple of solutions to this effect. One is to completely design everything ahead of time, so that there are no changes or surprises that occur during implementation. This approach suffers from the fact that most people find writing specifications even more boring than writing comments and documentation, and also that while well considered specifications will generally take most possibilities into account, nothing says that they too won't have mistakes or overlook something.

The second solution is some kind of editing pass. This is basically what I do. In the afore-mentioned article, Mr. McCraken discusses editing a finished piece of code to improve the clarity or the code itself, and in addition to doing this I've found that this is really the best time to add comments as well. The remaining trouble is that this works great when I have plenty of time to work on a project. Unfortunately, when I'm short on time, this is the most likely section of work to be cut out in the interest of speed. In fact, I think that that is the bottom line that this entire problem comes down to; when programmers are in a hurry, comments are one thing that they can leave out which will save time without affecting the performance of their code.