Liar, liar, pants on fire!

Before I start this diatribe, give me a minute to get up on my soapbox. Ah, that’s better. The air up here is not as polluted and I can see more clearly now. Too bad some of you can’t get up on the soapbox with me to enjoy the view, but I digress. OK, before going any further, I warn you that I am about to offend a lot of “kool-aid drinkers”.  If you are one of them, tough toenails, because I’ll give you the bottom line right now – you, my friend, are an idiot.  If you don’t have thick skin, read no further. Those of you brave enough to face the truth, continue on.

We here at Visionpace make every attempt to practice the Agile methodology of software development. We are proud of the fact that this practice serves both us, as software developers, and our clients extremely well. Many of our clients were reluctant at first, but once they understood the benefits, most of them gave it a chance and haven’t looked back.

Agile practices are a good thing, but I do have one beef that I am VERY passionate about and I am about to discuss (some of you might even say, proselytize) it. In many agile discussions, as well as discussions about other software disciplines, one often hears the phrase, “All comments are lies.” Those of you who believe this are (as I have alluded to above) idiots! However, those of you who do NOT believe it, COULD still be an idiot, and so, be sure to get a second opinion.

Hey, I get it. Don’t trust comments. They are not always accurate. Duh! I feel that there are a certain percentage of you out there who actually embrace this belief because it validates the fact that you were doing the right thing all those years by NOT putting comments in your code. No, it just validates that you are lazy. Lazy is not, necessarily, a bad trait in a software developer, but NOT commenting your code WITHIN the code makes you, dare I say it, an idiot. That is the last time I will use that term, because, hopefully by now, you are riled up enough to really listen to me.

Other than the fact that someone either knowingly wrote an inaccurate comment or wrote a comment, modified the code pertaining to it, and then did not update the comment, can any one out there give me a reason NOT to trust a comment you discover in code? We will exclude that person from the discussion because he is a “psycho programmer”; you know the one that NEVER follows any kind of standard and use one character mvars. Besides, most “psycho programmers” don’t comment anyway.

Here are the reasons why you SHOULD comment your code.

1. Let’s get the “trust” issue out of the way right now.  If YOU put the comment in yourself, you BETTER believe that the comment is accurate. You did it (primarily) for yourself.  The fact that an accurate comment will benefit a maintenance programmer who comes down the pike a year later is an extra benefit; a benefit which I appreciate when I am called in to do the maintenance. I will be more than happy to ASSume that the newly discovered comment is accurate because THAT developer put it in there and, like you, why would they want to lie to them self? Yes, there is that chance that the comment is now inaccurate.  Studies have shown, statistically, that approximately 93% of comments ARE accurate.  Right here, you should be asking yourself where I got those numbers, and right here, I will tell you that I made them up.  Who would waste their time researching that fact? Nevertheless, think about it, most comments ARE accurate because the person who writes them WANTS them to be accurate.

2. OK, I can tell you are getting a little bit peeved right now. Dave, I thought our code is supposed to be “self-documenting”? If I write bug free code, why do I have to comment? Oh, grasshopper, you will learn someday.  Until then, trust me, write those comments! In all honesty, I, too, am a believer that under most circumstances, the code SHOULD be self documenting. However, consider the following code:
   
   

REPLACE Name WITH UPPER(SUBST (LastName, 1, 2) + LOWER(SUBST (LastName, 3)

That code is self documenting, if someone wanted to take the time to figure out what it does, they could easily do so. The real question the person should be asking their self is... WHY is that code there? It looks kind of goofy anyway.  When I first saw it, I thought that perhaps the coder didn’t know about the PROPER function, but then, they were really capitalizing the first TWO letters of the name. Maybe the parameter of the first substring should have been 1, 1.  Maybe I should refactor using the PROPER function.  I am soooooooo confused!  Close to an hour of my time was spent determining WHY this code was here.  Imagine how much easier it would have been had the following comment been in place.

DLA/Visionpace 04-01-2004 Mr. Jones, the COO, bought 113 file cabinets at an auction. He has decided that the new company wide filing system will be based on the first TWO letters of the customer name. EACH drawer will have a two letter designation and the file will be placed in the drawer base on the first two letters of the customer name. To make it easier to file, he wants the first two letters emphasized for easier reading.

Immediately, we can see that the code is correct and that there is a reason WHY it was written.  Additionally, as often happens to me, in some scrum, when asked why this was done or who requested it, the answer is there.  Not only for me, but for you when you come in to do the maintenance. Two minutes to initially write the comment or 60 minutes to figure out the details three years later. You do the math.

3. Additionally, what one developer feels is self-documenting, another might not. Why not eliminate any potential confusion and explain the reason for the code’s existence? Again, it will save the next person who comes along much valuable time for there is a real good chance that they will know nothing about the project and the code. Believe me, you will benefit also.  One of my favorite phrases is... “When you are coding, you and God know what you are doing.  Six months later, only God knows.” I can not begin to tell you the number of times when I have gone into some legacy code and the comment I wrote three years earlier IMMEDIATELY brings back to life the exact reason for the code.  Many is the time that it has saved my fanny. Those are the times that I almost dislocate my shoulder patting myself on the back for a job well-done.
   
   

If you have made it this far, you are just not getting enough billable hours in.  However, thank you for reading along and agreeing or disagreeing.  Either way, I would appreciate hearing your thoughts on this very polarizing topic. I promise to bring an open mind if you do the same, but I will say right up front, that it will take a Herculean effort to change my mind.  Care to give it a try?