Ars Technica recently posted an article taken from Stack Exchange about comments in code. It’s a thorny subject with programmers. “Why should I comment my code – I know what it does?”.

Sure, you do. But what happens if I need to come and work on your code – in a hurry?

I’m speaking from experience here. Bitter experience. I’ve had to dive into code, in a hurry, to fix something, because a client is on the phone, screaming, and screaming loudly that this needs to be fixed. Today. Or There Will Be Consequences.

And the code was horrible. Layer upon layers of classes with cryptic but “self-descriptive” names. Sure, he was following the “Code Complete” method of working – “regard every comment as a personal failure”. “Clean Code” has the same thing.

Here’s a tip for you: take those two books, find the pages where it says this about comments, and cross it out. Because while both books are incredibly useful, they are completely and utterly wrong about comments. Their advice is harmful, dangerous, and leads to sloppy, unmaintainable code. It promotes a sheer lack of professionalism, and it’s dangerous. If either of the authors came to me for a job, I would turn them down, even if I were short staffed and they were the only candidate, for this reason, and this reason alone.

What I needed in that circumstance wasn’t “self-documenting code”, what I needed was signposts – I needed to be able to find my way to the trouble spots – fast. Even single-line comments giving a brief description of what the class did would have helped. I’ve worked on badly written projects that were more maintainable than ones that are paragons of excellent code entirely due to this issue. I’d take a well-commented, bug-ridden crawling horror over some comment-less mediocrity any day.

Comments are not a failure, nor should they be regarded as such. One answer they mention in Ars demonstrates exactly and precisely why comments – even bad ones – are essential, without even realising it. Take a look at this, from an answer by Paul:

They often lie. You cannot trust comments and must read the code instead. Which raises the question: why would you need the comments at all?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
//the calculation of the hash
int result = a*b;
}

(The hash is not the sum but the product.)

Sure, that’s a bad comment. But it documents what the programmer was expecting the code to do. If this is where the error is found, then it should raise alarm bells. Check your source code control logs (you do use Subversion, TFS, git, or something like that – right?). Is it simply a typographical error? Did it get changed for debugging and nobody changed it back? Did it get changed – even though it’s wrong – to get a badly written test to pass? I’d argue that the comment isn’t wrong here, not at all – it’s a clue as valuable as the curious incident of the dog in the night-time.

But let’s diverge for a moment – what if the comment were more illuminating?

// this method used to return the sum of 'a' and 'b'

or how about the even more useful:

// this method used to return the sum of 'a' and 'b'
// 1999.09.09 (SC) changed to be compliant with protocol v2

In reality, I don’t think anyone that doesn’t comment their code can, or should, ever be called a “professional” programmer. I’ve worked with many bright minds who develop over-complicated systems that have caused their colleagues problems when the inevitable happens, and they have to take over the maintenance of the project.

It’s not for nothing that Microsoft StyleCop bitches when you don’t comment what your code does. Much as I don’t particularly enjoy working with StyleCop’s rules, that’s one I’m totally in favour of.

In short folks, my attitude is simple: either learn to write effective comments, that signpost what the things you have written are supposed to do, or go find a job doing something else. Because until you can write effective comments that enable other people to modify your code, you’re not a professional who makes positive contributions at work – you’re a dangerous liability who is endangering your employer’s very existence.

Rant over.