Is Documenting Code a Necessary Evil or Just Plain Wrong?

Maybe it’s the nature of the Internet, but some months are just full of odd pronouncements. Last week, it was, "The DBA is dead!" (See "The DBA Is Alive and Well—Here's Why.") This week, some developers are announcing, "We're against documenting code!" As I understand it, the argument is that documentation itself isn’t code, and although documentation can be well intended, it only prevents you from understanding what the code actually does. The correct approach to documenting code, according to this line of thinking, is that you should be writing Really Obvious Code (ROC). The only necessary comments are for your methods, telling other programmers what data and data types they should expect in each method's parameters and then what the function should return.

Related: "A Day in the Life of a DBA"

As a former developer, I'm calling foul. There might be situations and certain types of code that can get away with such minimalistic types of comments, but for most applications—at least the types of applications that I have the questionable pleasure to work with—I don’t think that’s adequate. I believe that commenting your code is more than a nicety; it’s a necessity.

You Need Them More Than You Think

No doubt, part of what makes a great developer is his or her ability to write ROC, but in the corporate environment there are usually a lot of hands in the pie. The sad truth is that not every one of those contributors is a great programmer—or even a good programmer. Business applications often have a long, sometimes decades-spanning lifecycle. And there are times when you’ll be stuck working with code that uses poor or indecipherable variable names and questionable logic and flow. There are also times when you’re not sure what a given piece of code is actually doing, let alone what it was intended to do. Often, the person who wrote that code has been gone for years and the only clues you have for figuring out the puzzle lie in the comments. When that’s the case, you’re delighted with with whatever comments you might find in there.

I was a developer for a Fortune 100 company at my former job, and I distinctly remember a couple situations in which the comments saved a lot of time as I tried to decipher what was going on with the code I was working on. The most obvious one was a cost-estimating program for a corrugated-box manufacturer. Needless to say, this can be a fairly complex process, but the code worked as expected—except with one particular machine. Looking at the code revealed little at first; it looked OK to me. Fortunately, the comments described what the routine was supposed to do. Following through the code revealed a scoping problem in which a previous programmer had mistakenly created an almost identically named variable to the one the routine was working with. This variable was used for the local calculations, but sadly the code never assigned the contents of the working variable to the original variable. Sure, I could have found this problem without investigating the comments, but the comments gave me quick insight into some unfamiliar code, thereby speeding up the troubleshooting process. I’ll even admit that there have been times when I’ve gone back code that I’ve written—even code whose purpose I couldn't remember—and read my own comments to get an overview of what was going on.

True Believer

I’m a firm believer in commenting code: The more comments, the merrier. At a minimum, methods should begin with a description of their purpose as well as their input and output parameters. Long code blocks and loops should have a description that describes what the original developer intended. All code updates and modifications should have comments and dates that tell you the "who, what, and when" about the code changes. Just like the DBA, documentation is far from dead. As long as programmers still write code, there’s a need for code comments.