Clean Comments

One of the most interesting things I’ve found out about people arguing on the internet is related to code comments. Every time there’s an article about how to properly comment code it is followed by a heated discussion in the comment section. Two sides. One saying that comments are really, really important, and the other saying the exact opposite. Comments should be avoided when possibile.

What I’ve realized is that your stance on comments depends heavily on your experience, and it isn’t a linear progression from NO COMMENTS to PRO COMMENTS (or viceversa), it is more of a wave function. You usually start in the NO COMMENTS camp, when you are alone writing code for fun, then you go all the way to the PRO COMMENTS when you start dealing with other peoples code (or your old code) and spending hours trying to understand a function, and wish that someone had commented it. Then suddenly you go to the NO COMMENTS again when you have to deal with old lying comments that mislead you, and realize that developers won’t update the comments as the code changes. Then (at least this is where I’m now, who knows tommorow what I’ll think) you find some middle ground where you avoid comments where possibile and write them when you fail to write code that’s self documented.

That last phrase “self documented code” is used by people on the NO COMMENTS side, both experienced and not experienced programmers, so people on PRO COMMENTS think that when arguing about comments they are dealing with noobies, and maybe they don’t even know that exist experts whom are one the NO COMMENTS camp. These guys on the other hand have a really hard time breaking that first impression and everything they say just lumps them more no the noobie group.

There. Internet wars explained. Now let’s stop ranting and let’s see how to write good comments and what comments we should avoid.

First a¬† general guideline. I can’t recall where I read it but the best rule of thumb for comments I’ve found is this

Don’t write comments that say what the code does. Write comments that explain why.

I’ve seen comments like this, and I immediatly delete them

string x = start + end; //Concatenate start and end
int y = a + 1; //increment a

Those comments don’t help in any way. They just say in more words exactly what the code is alreday saying. They are noise, and the human brain is really good ad ignoring noise. I don’t want my brain ignoring comments, because comment can contain really important information, so when I see a comment that is noise I delete it.

What could have been useful in the previous snippet was a comment explaining why a was being incremented. Right now I’m left wondering, and if the code is written properly I should be able to understand while reading¬† more of it. But sometimes it isn’t possible to express intent with code alone, in these cases a comment can help clear things up.

The why behing a piece of code can come in multiple forms, like:

  • Explaining intent
  • Warning of consequences
  • Justifiing something that without proper context could look wrong – like in the case of performance reasons

Another kind of good comments are documentation comments on public API, but only if they actually add relevant information that can’t be inferred from the signature of a method.

The worst kind of comment are out of date comments, because it spreads lies. Obviously no programmer has ever written an old comments. Comments become obsolete after they where written, because they tend to not being updated.

Comments that you should avoid are:

  • Comments that leave too much to interpretation – if you are taking the time to add a comment, make sure it is clear
  • Redundat – like in the example before
  • Mandated comments – policies shouldn’t require programmers to write comments, because they will write lots of redundant comments. Policies should require clean code
  • Comments that try to do the job of a version control system. Like tracking who edited what, when and why. Use a VCS

A special place in hell should be reserved to commented out code. Be rutheless and delete it as soon as you see it.

It’s important to remember to never use a comment when a name would do a better job, like in the following examples

DateTime date; //last modified
DateTime lastModified;
void functionName(){
//Do this
//Do that
//Do something else
void functionName(){


Author: Maurizio Pozzobon

Maurizio has 5+ years developing solutions in the insurance industry. He is passionate about doing the right thing right, so he works in a tight loop with his clients to deliver the best solution possible.