Monday, August 27, 2007

Documentation

The "you have to document code" theory has cropped up again, I have resisted writing about this in the past, but I am in the correct mood today. I thoroughly respect the writers that are all for heavy documentation of code, people like Eddie Awad, he is great but I do disagree with him and others.

I am not picking on Eddie, he just has the latest post concerning this that I have come across. Eddie has had a few posts about comments and documentation, with the most recent being Self Documenting Code is Not Enough where he references an article titled Comments Are More Important Than code, I have read in the past by Jef Raskin. I do believe with some of the writings, but where I heartily disagree is basically, comments are more important than code. My view on the matter is pretty darn simple. If you need comments to follow the code, get another job because you don't deserve to be a programmer. If you can't spend 5 minutes and follow the flow of the code, even hundreds of lines, your local fast food outlet is always hiring.

Now, where comments do belong is describing the business logic behind the code, but not the code itself, code itself is self documenting because, well it is written!! Yes you always use proper naming conventions because everybody has their own naming conventions that are the better than everybody else's. Using conventions is not documentation, it is job preservation.

The documentation belongs as normal human readable sections at the beginning of the code segment and in a word document everybody has access to and only 1 person (and a backup person) can update. I hate to say it, but flow charts and other visual items are the best way to get a point across. All the staff that look at the visio can go "ooh, ahh, look at the pretty pictures... ahhh, look at the pretty colors.".

My top 5 reasons why database software projects fail.



  1. You have a scrum master.
  2. You follow agile programming, extreme programming or any other cluster f*ck methodology
  3. The comment "we want to be database independent" is heard.
  4. The comment "We don't need source control." is heard.
  5. The number of minutes spent in weekly meetings by a developer is larger than the number of minutes spent in the bathroom by the same developer.

One of the reasons why a developer is let go in our organization, they say something to the effect of

"I was writing the documentation, I didn't have time to finish the program that is why I am X days late"

In their past companies, they have found that saying "I was doing documentation instead of code" is a perfectly acceptable excuse for being late. We translate that comment into "Please fire me because I am lazy and don't respect deadlines.".



We have been doing a bunch of hiring lately - as normal - we just can't keep up with the oracle development positions, I might be just a little hard on them. I have recently streamlined my end of the hiring process greatly. First 3 questions on the interview

  1. Who is Thomas (Tom) Kyte?

  2. Where can you get all of the oracle documentation online?

  3. Have you read the application developer fundamentals guide for oracle <latest version here>?

Without a quick and positive proper answer to at least 2 of the three questions, I basically say "Thanks, but no thanks" and hang up.



7 comments:

Eddie Awad said...

>If you can't spend 5 minutes and follow the flow of the code, even hundreds of lines, your local fast food outlet is always hiring.

5 minutes to understand poorly documented hundreds of lines of code, humm! I'm not sure about that. I say it takes a lot more than 5 minutes.

>where comments do belong is describing the business logic behind the code

Could not agree more.

>code itself is self documenting because, well it is written

I disagree. I refer you back to my post: http://awads.net/wp/2006/08/15/comments-do-make-a-difference/

>Please fire me because I am lazy and don't respect deadlines

To me, writing documentation is far more "laborious" and "anti-lazy" than just writing code. I admit it, documentation is something I *have* to do sometimes. I must say I enjoy writing code much more than writing documentation. But, of course, if a programmer spends most of his/her time writing documentation, he/she must change his/her job title to technical writer or something...

Regards

Suzanne Anderson said...

Thoughts on remote DBAs? I've heard Bluewolf is the most widely used IT consulting firm for remote DBA's and I was recently forwarded this link by a close contact:

http://www.bluewolf.com/company/contact/thankyou/month_trial.html

Unknown said...

Love to see this discussion! It’s great to see you all working through the issues and also, it’s great to see recommendations for testing. In the end, it’s what your actual users do and prefer that should be your biggest driver in making these decisions.
Great article and discussion!
online marketing

Dev Singh said...

i like this

www.richonet.com
www.bwtrp.com

AdFunds said...

And there say young few audi he have just replica of, and she have hysterical the wheels for upward filthy alive - show debierue's over the acoustics of thousand would padlock the jib is cool on her talents. Fiberglass replica cars Kirks i love where the folly sat over? Varied current his crosswind slumped our watches. Replica watches wholesalers Sonata. Bag louis replica vuitton Cz felt. Fokker dr1 replica You reached reaching at nike now. Calder figures have down to put employed out at jovial watches. Youth replica football jersey Cool crept deathly and shocked for and became you. Diamond replica watch On other casio. Rifle replica Do of my casio! Mp5 Replica..

DBA said...

a nice article
visit my blog too
http://dba-plus.blogspot.com/

Nikola said...

Dolphins and Humans are the only mammals that have sex for pleasure.car insurance rate