Diminishing chaos

Following Tom Kyte's Blog I was introduced to the "Geek and Poke" comics. Maybe because I'm in a crazy working phase that makes me want to find fun in work (the kind of fun that makes you laugh about yourself and your work), tonight I spent some time browsing it, and briefly I found some very good amusing ones.
From the first one I show below I start writing this post about documentation and then I found out some other strips that are perfect to make you not forget the message (or at least smile a little :-))



It's soo true!

(Most *) Programmers do not like to comment or are use to comment code.
His own code it's self-explanatory, right? Of course good variable names can help figuring out what is happening at first (or second or third...) glance, but without commentaries (good ones and up-to-date) you will need sometime to figuring out what is happening ...in this I include specially SQL code...

As Steven Feuerstein says "we (developers) like to solve puzzles", we solve one puzzle and then rush looking for another. "Because we never make mistakes and our code is bug free!".

Reserve your comments to explain the Why of your code: What business rule is it meant to implement? Why did you need to implement a certain requirement in a certain way?

- Oracle PL/SQL Programming, 2nd Edition, chapter 3

I think that almost as bad as no commentaries it's the old-dated obsolete commentaries: the ones that mention old features or process workflow that only exists in some very old version...

My advice start every day to invest (not spent, mind!) 15 minutes commenting the code you are working with (be that your own or another) and if you change something that will make a comment obsolete correct the comment.

I know you will say "that will take more than 15 minutes" but I want to motivate people to do it. Baby steps...start slow ...do not try to comment all...I know that you need to write more code...and with practice it will came more naturally figuring out where comments are needed...

It's up to you that start diminishing the chaos!

Following Murphy Law's here is a corollary (made by me ...maybe there are others related):
"If the code is documented you will never need to fix it and you will never look at it again.
If the code is not documented you will have to look and fix it several times."

or in a sentence:


"You can be sure that the code you need to fix or read will not be documented."

* I had to add those two bits to avoid some flame mail :-)

Good codding and good documentation