Wednesday, June 09, 2004

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... "

4 Comments:

Anonymous Anonymous said...

That would be my entry. You misread it.

Taking your example, the comment you added would be fine. However, this comment would not be:

// Loop through the oldNumber string. For each
// character in the oldNumberString, if it's a digit
// we append it to the newNumberString, otherwise if
// it's a (, a space, a x or a X we stop then and
// there.

Still, I would argue that even your one-liner comment might be too much. Instead, extract the body of code out into a method called "stripTrailingPhoneExtensionForGroupX" and give that method the one-line comment you gave as Javadoc.

I strongly believe that code should be made clear enough that it doesn't need "how" style comments. If the code needs a comment, the answer is to write the code better in the first place. For the 2 seconds it takes to write the comment, you can spend it doing an ExtractMethod refactoring.

Your 100,000 line systems that you have to deal with are fully of shitty code (evidence: appending to a String inside of a loop!). If it was commented, it would then be commented shitty code. Why not want good code?

Robert Watkins -- http://twasink.net/

June 09, 2004 10:43 PM  
Anonymous Anonymous said...

I'd like to put my hand up in support of commenting code. Commenting code allows you to read chunks of code via a one-line summary. I even comment stuff that's for my eyes only, since I'm such a forgetful creature.

December 20, 2004 10:39 PM  
Anonymous Anonymous said...

Amen! I vote for COMMENTING the code!

December 22, 2004 8:24 AM  
Anonymous Anonymous said...

I agree.. commments in the code not only helps the person who writes the code in future.. but also those who are totally new to the code and would be working on it.. however, it requires discipline on the coder's part!

January 23, 2005 6:50 AM  

Post a Comment

<< Home