« Are Ya Catchin' This, Camera Guy? | Main | K.O.K.O.P.E.L.L.I. is koko-licious! »

September 30, 2009

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 again, 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, in MY opinion, you SHOULD comment your code.

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.

 

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 parameters 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, recently 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 five years later. You do the math.

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?

Posted by Dave Aring on September 30, 2009 | Permalink

TrackBack

TrackBack URL for this entry:
http://www.typepad.com/services/trackback/6a00d8341fba8753ef0120a5ae3f47970b

Listed below are links to weblogs that reference Liar, liar, pants on fire!:

Comments

Hi Dave,

I've been practicing what you preach for a long time, and I wholeheartedly agree. Countless times I have had to go back to code written years ago by a less experienced version of me, and my comments have proven invaluable. However, I have also experienced an immediate benefit to comments on many occasions. When writing new code, I may hack away at one or more functions or methods -- *without* writing comments -- until I pretty much have things working the way I want. I then go through and comment what all the code is doing. It's at that point that I'll see that some code can be streamlined, or that I overlooked something that the code needs to do, or that a method is trying to do too much and needs to be split up, etc. Basically, commenting my code forces me to perform a code review on all my code.

Posted by: Mike Potjer | Oct 1, 2009 12:20:23 PM

Mike…

It is always nice to have a “heavy hitter” like you in my corner. Thanks for the kind words and additional food for thought.

It is not my intention to get converts; I just want to counter the “comment myths” that are perpetuated and, in my opinion, dissuade developers from commenting their code because they give credence to the belief that it is OK to NOT comment. For me, the bottom line is knowing that, for me, comments are “multi-taskers”. Like you, they have served many purposes and help me out in many ways over the years. Definitely a classic case of “the proof is in the pudding”. There is no better evidence than hands-on proof from real life experience that comments are very useful. Unfortunately, it is difficult to convince non-believers to comment because until they experience the feeling of sassyness (self-satisfaction?) that comes from having been helped out by one of your own comments (generated a couple of years earlier), they have no sense of their real importance.

The people who really annoy me are the ones who complain about all of the wasted space and additional words that have to be read when reviewing code. To them, I would suggest that they change the IDE comment forecolor and backcolor to black on black and give their code the appearance of a released Watergate document. That, or ReFox the exe and eliminate the comments altogether.

Oh well, live and let live. I know that I will be living with comments.

Bestest,
…Dave

Posted by: Dave | Oct 1, 2009 3:05:09 PM

Hi Dave,

No comment [gd&rvf]

Just kidding, I wholeheartedly agree with you and Mike.

The only thing I would add is that I've heard it's good to comment *why* something was done (as opposed to commenting *what* something does).

Posted by: Art Bergquist | Oct 1, 2009 4:28:08 PM

Art...

You are definitely correct. I did allude to that aspect, but, perhaps, I didn't emphasize it enough. YOU said it succinctly. Thanks.

See you in Mesa in a couple of weeks. That goes for you, too, Mr. Potjer.

...Dave

Posted by: Dave Aring | Oct 1, 2009 5:04:51 PM

Heh - great post - although I do question the need for a 5 line explanation of a single line of code. Wouldn't it suffice to say "Due to COO's change in file cabinets 10/5/2009" or "refer to file cabinet spec"

Posted by: Andrew | Oct 14, 2009 4:43:24 AM

Andrew...

EXCELLENT point, although I actually hate to admit it. In any job interview, when asked about "one of my weaknesses", the word, VERBOSE, usually is a part of my answer. I am aware that my "wordiness" can be annoying at times, but since I was vaccinated with a phonograph needle, I find it hard to "throttle back". I guess the epidome of this affliction was one time when a boss asked me a question and IMMEDIATELY after he asked the question, added... "And Dave, remember, when I ask you what time it is, don't tell me how to build a watch."

Bottom line... your suggestion is well-taken and I should be mindful of more succinct comments; perhaps if we had to Twitter our comments.

Posted by: Dave | Oct 14, 2009 9:27:50 AM

Hey Dave,

Great read. Andrew, you have specs to refer to?!! I agree in comments lengthy enough to stand alone.

Jim

Posted by: Jim | Oct 14, 2009 4:42:33 PM

Jim...

What can I say? When you are right, you are right. Thanks for the kind words.

...Dave

Posted by: Dave Aring | Oct 14, 2009 10:48:14 PM

You are definitely correct. I did allude to that aspect, but, perhaps, I didn't emphasize it enough. YOU said it succinctly. Thanks.

Posted by: Deepak | Sep 17, 2011 4:39:57 AM

You are definitely correct. I did allude to that aspect, but, perhaps, I didn't emphasize it enough. YOU said it succinctly. Thanks.

Posted by: Deepak | Sep 17, 2011 4:39:58 AM

You are definitely correct. I did allude to that aspect, but, perhaps, I didn't emphasize it enough. YOU said it succinctly. Thanks.

Posted by: Deepak | Sep 17, 2011 4:39:58 AM

You are definitely correct. I did allude to that aspect, but, perhaps, I didn't emphasize it enough. YOU said it succinctly. Thanks.

Posted by: Deepak | Sep 17, 2011 4:39:58 AM

The comments to this entry are closed.