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.



Tuesday, August 21, 2007

Oracle 11g

Well. Since everybody is talking about oracle 11g, and I have been really quiet lately... I took today and installed oracle 11g, then I upgraded a test database to 11g with zero problems.

I ran some of our testing scripts and performance and results matched what had been documented earlier in the month. So, I bit the bullet, I upgraded a production database to 11g. Now, when I say "production" I mean a 3 user database coming in at just under 2 gig in size including system tablespace, so awfully small. It is simply a way for users to search for files that were created before 2000 and was simply 5 spreadsheets compiled to a common format and loaded. It is a recent addition to our systems and I have all of the base data that can be loaded again.

So, we are successfully running an oracle 11g database in production.


Woot Woot.



Monday, August 13, 2007

SPAM

Due to the LARGE amount of spam this blog is getting, I am going to switch comments to registered bloggers only. Sorry all, but I have had enough of deleting the SPAM posts. Death to all spammers.

Friday, August 03, 2007

Don and Jonathan at it again

Once again they are at it.

http://forums.oracle.com/forums/thread.jspa?threadID=527201&start=0&tstart=0


All I have to say on the matter is, Don Burleson and his employee comments, scripts, "how to's" and expert advice have screwed up more than one thing mostly due to me trusting them without actually paying attention to what was going on. Nothing from Jonathan Lewis has ever failed me.
Don Burleson has an interesting outlook on life - check out his personal blog - I won't link to it, but just google it "don burleson blog personal" and it is the first hit.

Rather enlightening to see a his view on life.