Your instructors got it wrong

I remember doing this sort of thing in college:

i++;    // Increment i by 1.

Why? Because they beat into our brains how everything should be commented.  That comment does nothing but clutter up the source.  It tells you what I intended, but has no bearing on what will actually happen. I should have lost points for that mess.

Let’s face it.  Comments in code suck.  Here’s why.

1. It’s probably out of date.
2. It distracts me from what your code is ACTUALLY doing.
3. The compiler doesn’t care about your comments, nor does the run time

I’m only going to focus on point 3, because 1 and 2 follow from it.  At the end of the day, the only thing that matters about your code is how the computer interprets it.  I don’t really care how you wanted me to think about the code.  Don’t get me wrong… I know there are two audiences of code: the compiler/runtime and the developer. I’m just arguing that comments typically do not help the understandability of the source.

Now I will say that I comment code that sucks.  Sometimes you have to do something ugly and I don’t want someone believing that it’s ok to repeat what I just did.   This is where the adage that comments are deodorant for code applies (btw, that author makes a great point regarding writing comments only to answer the question “why?”)

Let me clarify one other thing.  I’m not against comments that produce documentation, a.la. javadocs, scaladocs, etc.  That’s awesome.  In fact, you’ll set me off on a rant for NOT doing those types of comments.

The reality is, sometimes we gotta throw comments in there to let the reader know why you’re doing what you’re doing.  One thing I’d like to see is comment scope.  Just like how a javadoc applies to a class, method, field, etc, it would be cool if a comment could be declared as applicable to a chunk of code.  This would be good for when I use more than one line to do something ugly.  It doesn’t solve any of the problems I’ve mentioned, but at least it lets the developer realize that he is touching code that might alter the accuracy of the comment.

My colleague stated my position best:

To me, comments are like code:  the less there is, the better. And like the code, if there are comments, they need to be right.

Which, by the way, is why long variable names is NOT the solution to less comments because it creates more code.  Besides, it has all of the same problems mentioned here.  I’m ok with long names for public API (see my comments… ahem… regarding documentation).  That can be annoying to the consumer but thankfully my favorite language Scala (favorite at the moment anyway) has the brilliant feature of import renaming.  I rename all sorts of stuff to single letters so it looks more like my first love, math.

Thanks to this blog for inspiring this rant, although I think the real point of the blog was about type checking… and it was a very good one.

Image may be NSFW.
Clik here to view.

Image may be NSFW.
Clik here to view.