/** Comments in Code? Yes, Please! */

Yet another weekend is here and I was browsing when I came across an article which said “Comments in code should be avoided”. I’ve come across several articles and blogs that talks about more or less the same idea. In fact, it seems to be an emerging trend nowadays. Some people say code should be self-documenting so that you don’t have to write comments. Some others seem to think if you need comments to tell what your code is doing then it’s time to rewrite the code. That way it’ll become easily readable and then you can forget about the comments. 

I like the part that says “write easily readable code”. But avoiding comments altogether? Somehow I don’t find that so appealing.

Why comments are needed?

Software engineers spend a good deal of time writing code which also involves tasks like picking the best algorithms for a specific task, debugging and revising the code as required. But there’s no guarantee that the code will always be maintained by the original author. It will be used, modified and maintained by other engineers tomorrow. Easily readable code is a pleasure to maintain and makes it easier to understand what is being done there.

But there’s something else that code cannot easily capture. That is the intent and your thoughts while writing that code. That’s exactly why we need comments. We don’t need comments to tell us what the code is doing, we need it to tell us why it’s being done that way.

Types of comments – Good, Bad and the Evil

I can think of 3 ways to add comments

Type 1 – Bad code, Bad comments

//Find f by multiplying m and a

float f = m * a;

This kind of comment and code should be completely avoided. This doesn’t give a clue as to what f, m and a is. 

Type 2 – Good code, Bad comments

//Find force by multiplying mass and acceleration
//

float force = mass * acceleration;

The code looks good with meaningful variable names. But why do we need this comment ? I already know how to read.

Type 3 – Good code, Good comments

//Find force using Newton’s second law

float force = mass * acceleration;

This is so much better. I know what you’re doing and why you’re doing it.

Another Example

In distance calculations, a lot of times we use Pythagoras theorem.

Type 1

//find c by adding the squares of b & c and then taking its square root
//

double c = Math.sqrt ( a*a + b * b);

Type 2

//find thirdSide by adding the squares of firstSide & secondSide and then taking
// its square root

double thirdSide = Math.sqrt ( firstSide* firstSide + secondSide * secondSide);

Type 3

//find length of the third side using Pythagoras theorem 

double thirdSide = Math.sqrt( firstSide* firstSide + secondSide * secondSide);

Now to someone with a mathematical background it will be clear we’ve used Pythagoras theorem for right triangles here. And if he has no mathematical background he can do a search and find the relation between the length of hypotenuse and the other 2 sides in a right triangle. He will also figure out that this can only be applied to right angled triangles.

These are trivial examples where comments come in handy. Production code is sometimes much more complicated with thread pools, synchronization and so on and comments can add a lot of value there.

What does all this mean?

There are right and wrong ways to do a thing. If you do it the wrong way it won’t be of much use. But that’s the case with everything. A knife can be used for chopping vegetables or for hurting someone. Just because the second possibility exists doesn’t mean we should stop using knives altogether. It’s the way we use it that matters the most.

Adding Type 1 and Type 2 comments is not of much use but Type 3 comments can come in handy later.

That said, the choice to add useful comments is up to the developer unless of course your organization mandates it. Even if no comments are added to a code, the developer working on it will finally figure it out even if it involves running the code multiple times with multiple breakpoints, some log messages, stack dumps and so on. But do we want to put them through all of that ? Why not make that a little easier by adding useful comments and make this a better place for all of us.

 Or there might come a time when you have to go back to the code you did 5 years ago and you’re forced to add the following comment

//When I wrote this, only God and I understood what I was doing
//
//Now, God only knows