On Comments

Topic: Programming

Comment: noun a note in explanation, expansion, or criticism of a passage in a book, article, or the like; annotation.

Today I'd like to spend a little time talking about the controversial artifacts which are known as comments, and my current stance on commenting.

Each programmer knows what a comment is. However, for starting programmers, or people who are interested in programming but don't know anything about it yet, a comment is basically written text in a code file (also known as the source code) which will not be interpreted as code. It is basically text which is not part of the program. In most languages, they are usually marked by either two slashes (//) or a hash character (#). The following is an example:

int x = 0;
// Setting x to 1
x = 1;

As you can see, we are initializing a variable, x, to the value of 0. Then, we set the value to be 1. However, in between we have text saying what we are about to do. That text is clearly not part of the executable code; that text is known as a comment.

Now, the programming community is divided as to the usefulness of comments in code. One side states that comments improve code readability and should be used as often as possible. Using comments will also help new developers understand legacy code much faster, code which may be extremely confusing to read (confuse code). The other side states that comments are completely useless and can be replaced by good programming. The code should be in an of itself clear to understand, and that if comments are needed then the code is bad (bad notation). Additionally, people tend to rely too much on comments and place them in useless places (comment abuse).

Before stating my own opinion, let me show pseudo-code examples that I have encountered of both extremes. First, let us look at an example of confuse code:

int a = Math.sqrt(Math.pow(xValAfterModification, 9));
int b = methodFoo(a);

What is a? What does it represent? What is xValAfterModification, why are we raising it to the 9^th power and why are we taking the square root of that? What does methodFoo do and why are we setting b to this? No matter where this code is found, this is extremely messy and hard to understand. Someone would have to spend a long time looking at this to understand what exactly this is doing.

Here is an example of bad notation:

// This variable will store the current product price
int n = 0;

At first, this seems okay. The programmer is simply specifying what the variable will be used for. However, in this case the comment is completely useless. Why doesn't the programmer simply rename the variable n to currentProductPrice? No one ever confuse something called currentProductPrice with, say, the number of available products. In this case the comment is used instead of good programming practices (specifically using clear variable names).

Finally, let us look at an example of comment abuse:

// Creating x and setting it to 0
int x = 0;
// Adding 1 to x
x = x + 1;
// Multiplying x by 2
x = x * 2;

Ignoring the obvious uselessness of this code (why didn't they just set x to 2?), the comments in this example just state exactly what the code does at every step. However, the comments simply state exactly what the next line is doing exactly as if the person would read the code out loud. These comments are useless since they state the obvious.

Now, what is my stance on comments? Well, I sit pretty much in the middle. I believe that code should be easy to understand without the need for comments. However, let us look at the following example:

x = x + 1;
x = x + 1;

Now, why did the programmer increment x twice instead of simply incrementing it only once?

// x is a control variable. Due to the
// volatile and multiconcurrent nature of this program,
// we need to increment this varibale
// twice instead of just adding
// 2 to it.
x = x + 1;
x = x + 1;

Ah, now the reasoning is clear. Since the program is multiconcurrent, the programmer wants to increment the value twice instead of just once. There might be other questions someone can ask (is x used to view the number of modifications? is x written in another thread?), the comment adds clarity to the code in a way that the code could not do itself.

As such, I believe that comments should not explain the how of code, but should be used to explain the why of design decisions.

Now, I'm curious to hear what you think of comments. Have an opinion? Then leave a comment! (Yes I am a shameless sellout.)

Anyways, that's it for today folks. Stay cool,
Snowman