The Myth of Comments

Its been hammered into us since we took our first seat in the programming 101 lecture hall. Its been dogmatically programmed into each of us as if a religious script. I have seen developers scoff at code that lacks them and mistrust the behavior of said software. Because the myth crosses the boundary between technical and non-technical I've seen project managers require them and salesmen tout them. Of course, I'm talking about comments and the myth that they are an undisputed Good Thing. If the ultimate goal for a software project is to deliver business value the penultimate goal should be to communicate the what and how of that value. I simply do not believe that comments are the best way to communicate.

Developers have become such slaves to the myth that they start writing comments solely for the sake of writing a comment. This usually results in wasted lines on the screen telling me something that I as a developer should be able to infer from the code itself. I feel ill when I read code that looks like this:

// initialize an integer and set its value to zero

int i = 0;

// increment i

i++;

Yet this style of comments run rampant in posted code (yes even code posted on "reputable" sites such as CodeProject and MSDN), open source and commercial code! Commenting for the sake of commenting is an insult to the software profession. Please don't waste our time with these comments. Strip them out completely.

My foremost complaint is that comments (like other forms of documentation) can go out of sync with the code. Anecdotally, I've seen plenty of Perl scripts with concise algorithm explanations embedded in the code that differ completely from the actual behavior of that script. In this case the comments become not only an annoyance but a real danger as developers trusted the comments as if it were code. But comments are not code! Comments are not business value! Why should we trust the communicated message from anything but the code itself?

While I appreciate the spirit of communication that motivates comments, I think as software professionals we can do far better to fully communicate. For starters, we can strongly bind the message we are communicating to the business value itself by introducing a method through refactoring that is named by the message itself. For example, consider changing the following code from:

public void DoSomething(double r)

{

// Calculate the area of a circle using Area=Pi*radius^2

// where PI = 3.14

double a = 3.14 * r * r;

foo(a);

bar(a);

}

To:

double PI = 3.14;

public void DoSomethingElse(double radius)

{

double area = CalculateAreaOfCircle(radius);

foo(area);

bar(area);

}

private double CalculateAreaOfCircle(double radius)

{

return PI*SquareOf(radius);

}

private static double SquareOf(double radius)

{

return Math.Pow(radius, 2);

}

The result is an explanation as concise as the original comment. The difference is that when the code changes, so MUST the message. As a believer in and practitioner of software professionalism I am more comfortable knowing that the behavior and message will not go out of sync.

In fact, a goal of software professionals in modern languages should be to bind message to behavior by making the code itself read like a book. Lets lose the grip of the myth and shift from being coding automatons to thoughtful individuals passionate in our pursuit of improving the state and image of our profession by improving the quality of our primary deliverables: business value and the communication of that business value.