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

9 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  
Blogger tweedledeetweedledum said...

This blog is awesome! If you get a chance you may want to visit this graphic software site, it's pretty awesome too!

October 01, 2005 3:17 AM  
Blogger Frank said...

Looking forward to reading more great info on your blog, I added you to my favorites and will be checking back often.

My site is about make money home based business

If you have an interest in make money home based business I would love to hear what you think of my site.

October 01, 2005 5:52 PM  
Blogger TS said...

Nice Blog!!!   I thought I'd tell you about a site that will let give you places where
you can make extra cash! I made over $800 last month. Not bad for not doing much. Just put in your
zip code and up will pop up a list of places that are available. I live in a small area and found quite
a few. MAKE MONEY NOW

October 02, 2005 1:40 AM  
Blogger Mark Hultgren said...

Hello, I just wanted to post a comment on how well you have put your Blog together. I was doing a search for business home residential security system and came across your Blog. I personally run my own Blog for business home residential security systembusiness home residential security system so I know a good Blog when I see one.

October 02, 2005 10:15 AM  
Blogger Frank said...

I enjoyed reading your blog.

Do you have an interest in make money now? If so, I have a make money now site.

I'd love to have you visit and let me know what you think.

October 02, 2005 4:12 PM  

Post a Comment

<< Home