Coding Guideline #1: Save your coworkers sanity - comment your code!

I would have to say that I couldn't disagree more with this blog entry I read today - I spent most of my day shaking my head ... Perhaps this is a joke - but others are chiming in in agreement, so I'm left shaking my head...

I'll start by saying why comments are important ... Code changes (as is mentioned in the blog above)... And because it changes frequently (diverging from all documentation written about it)... Almost always, code is the only current view of the system - and this is the reason that commenting code is so important...

A bit more background about myself... I work primarily as a consultant... On lucky occaissions I come into a project at the start, but most of the time, I'm coming into pre-existing projects that are on the brink of disaster ... The systems I'm working on are usually 100,000+ lines of code... They've been around for years, they've been touched by upwards of 20 developers, and numerous business analysts / projects have tweaked requirements over this time... If I'm lucky I can get my hands on a UML tool, to give me a high level view of the relationships between major objects in the system... A good tool, will suck out the javadoc class / member comments... Without a UML tool, I can still javadoc the system (which I'll do with a tool or not)...

Here's a nice summary about How to Write Doc Comments for the Javadoc Tool ... Every Java developer should read this over, and if you haven't read it lately, go and skim it again...

On top of the guidelines for javadoc, it just makes good sense to place comments where-ever you feel someone would ask: What? Why?

When someone is making an esoteric change to a piece of code, it takes them 2 seconds to add:

// Stripping trailing phone extensions for contact numbers for other group X, system XYZ... 

rather than:

/**

 * I'm too lazy to write 10 words, figure this out yourself... This is in the middle of a 1000 lines of

 * code, in one of 100 java files...

 **/

String newNum = "";

keepGoing = true;

for(int c=0;c  char ch = oldNumber.charAt(c);

  if (ch >= '0' && ch <='9' && keepGoing) {

    newNum += ch;

  } else if (ch == '(' || ch == ' ' || ch == 'x' || ch == 'X')) {

    keepGoing = false;

  }

}

... And I'm being generous by using semi-meaningful variable names...

A junior programmer is not going to learn anything from stepping through that code by hand... it's not rocket science, but it's not great code...

When I start work on a new project, I get all of the source, as much documentation on the system as I can get my hands on ... If I'm lucky, there's a system design doc that's only a few years old, requirements a few years older than that... And that's typically all of the external docs... The requirements doc was written by an analyst that didn't initially understand the business process fully, so they missed documenting about 1000 business rules ... Those rules were added after users opened bugs (if we're lucky enough to be using a bug tracking system), otherwise someone got an email from someone else who sent it from someone else, mentioning that group X can't handle extensions in phone numbers and we have to strip them off... So a developer, before one of the releases added some code to do that... No requirements docs were revisited, the testing group wasn't notified, the behaviour is deep within the system, and the change went un-noticed for 2 years, until someone in group X makes starts accepting extensions on phone numbers, and wonders why our system isn't sending them to him... Now some poor junior programmer has to comb though a 100K lines of totally uncommented code...

To sum up:
Java provides a framework for documentation... Use it... Keep your in code comments up to date... I've never in my career heard... "Damn that Chris - he wrote too many comments in his code - he makes my job too easy... "