• Home
• About

Come on Code Boy, Talk to me!

Posted on March 17, 2007
Filed Under Uncategorized | 1 Comment

Why don’t developers document their code?  It’s not hard – just tell me what you’ve done.  Over the years I’ve come to accept that documentation is just one of those things that is seldom done well on software projects.  Even some of the most experienced software teams fail to deliver adequate documentation.  “Chill out Cleve…”, they chant, “…documentation is dull, code is cool”, oh brother, here it comes,  “didn’t you know Cleve, the code IS the documentation.”.     Somebody eat me!

 

Undocumented, or worse still, poorly documented code is a major bug bear of mine.  It is something that never ceases to amaze me in software development circles but at the same time makes my blood boil.  I see it as a lack of discipline that as professionals is something that every developer should do off the bat,  without being told.  A note to these document averse developers, you are NOT the only developer in the world!  What you write, either closed or open source, has a good chance of being read by someone else.  Strange but true, so please help that person. 

 

Most experienced programmers must have been on the receiving end of maintaining and/or upgrading software that was written by someone else!  As you read other peoples code, you think “who is this fool and why did they implement things this way”.  99/100 the code is not adequately documented.  Sigh!  Without documentation, you have to re-solve a well-understood and previously solved problem.   What a waste of time and effort.   It’s like bringing in Starsky and Hutch, Kojak and Columbo to resolve the case everything someone needs to review the murder file… 
 

But, do document averse developers learn.  I don’t think so.  Do, these once scorned programmers try to make the world a better place by writting well-documented code.  I should co-co!   Sometimes I think that some programmers believe they are writing self-documenting code that everyone who’s going to maintain their masterpiece in future is inside their oh-so-clever minds.  Sorry, I’m not as clever as you, so please help me!

 

Now don’t get me wrong, I’m not mad.  I’m furious!  Why do “professional” developers have to “told” to document their code?   Why do development teams have to told to write release notes and/or readme.txt files if their code is going to be used by somebody else.  Somebody on the over side of the world!  This is strange.  This is wrong.  This needs to change.  

 

I fell ill a couple months back so I went to my doctor and they gave me a prescription to take to the pharmacy.  So I did.  I got two bags back.  The first bag contained a bunch of pills of various sizes, colours and smells.  The other bag contained a number of liquids in unlabelled bottles.  I looked at the pharmacist.  She looked at me and said, “I’ve done my job, so go heal!”.   I looked at her as though she’s mad.  How am I supposed to do that if there are no instructions?  When, in what order, in what quantity am I supposed to take these things?  Are there any side affects for downing them in one?   I give exactly the same look to my development teams that deliver me undocumented code.  Sometimes, they just don’t get it.  Other times, its like, oh yeah, we should tell you at least something about what you’re getting and how to run it up.

 

I could go on and on, about things like your tests are part of the source code, so document them as well!  You don’t need to document the obvious like accessors and mutators unless they do something out of the ordinary.   Why not document as you go, then its never a chore.  There is a big difference between writing the function prototype and documenting it.  Both are a different view onto a same thing, but provide a more complete understanding when both are done.  If you wish to document later, fine, but just don’t forget to do it.

 

So code boy, talk to me.  Document your code.  Leave me some clues.  Is that too much to ask?

Comments

•