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.

Advertisements

Author: Robert Watkins

My name is Robert Watkins. I am a software developer and have been for over 18 years now. I currently work for people, but my opinions here are in no way endorsed by them (which is cool; their opinions aren’t endorsed by me either). My main professional interests are in Java development, using Agile methods, with a historical focus on building web based applications. I’m also a Mac-fan and love my iPhone, which I’m currently learning how to code for. I live and work in Brisbane, Australia, but I grew up in the Northern Territory, and still find Brisbane too cold (after 16 years here). I’m married, with two children and one cat. My politics are socialist in tendency, my religious affiliation is atheist (aka “none of the above”), my attitude is condescending and my moral standing is lying down.