How not to comment code

I’ve often encountered the attitude that code or scripts should be commented to the extent that someone unfamiliar with the language being used can understand what’s going on. I most recently encountered this with a set of Ant build scripts I had developed.

Doing this would be bad.

Why would it be bad? Let me quote the message I gave the last time I was asked this:

Production code shouldn’t be treated as a tutorial exercise to educate people; eventually, the comments get out of sync with what’s actually done, and at that point you’re misleading them instead. It’s far better to leave them in the dark so that they actually look up the right answer (or, possibly, even ask!) than assume that the half-incoherent ramblings typed in above are relevant (My comments are always lucky to be half-incoherent). This goes for Java code as much as build scripts. Okay, yes it means your junior developers are slower. But it also means that they’ll learn faster, and thus get to a higher level of productivity faster.

If people are given an explanation that covers what they see in front of them, they won’t go off and learn for themselves. If they won’t learn for themselves, they won’t be able to grow and develop. If they don’t grow and develop, they’ll never cease being junior people.

I make it a point to actually sit down and understand what’s going on when I get given something I’m not familiar with. This means I quite often spend time looking up manuals and tutorials via Google. Case in point: I’ve never worked with perl, but I was having a problem with the Movable Type code (a plugin, actually), and needed to figure it out. So I pulled up a perl reference and worked out what the problem was and fixed it.

As IT professionals, we should never be afraid to admit we don’t know something. We should only be afraid to admit we don’t know where to start looking to find out.