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.

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.

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.

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.

BAAG

I joined the BAAG party awhile back - Battle Against Any Guess.

Go and give it a read, especially you folks that send emails that have a subject of PLZ HELP or URGENT PLZ or something similiar.

User tracking

This is so obvious - at least to us here - that it really kind of shook us up that we were not doing it. I was talking to ,y friend Jeremy, and he mentioned his company had rolled out an internally built APEX app for tracking users and their accounts across all of the applications in the company. It took him awhile of explaining before it dawned on me how good of an idea this is.

They (as do we) have a database that is used for tracking employee phone numbers, with the multitude of payroll systems acquired through acquisitions having a single repository of all the active employees in the company that can be referenced even if those employees do not have network accounts is very important. We use our central database basically primarily for a place to allow employees to store their phone numbers and other contact information that is then access via a few JP pages. Jeremy and crew went a few steps farther. They actually replicate the employee information into this central database from all their various payroll systems, so that the information in the central database for where the employee is working, name changes, terminations, new hires etc is automatically looked after, so there is no out of date information when somebody transfers or quits. They then (and this is the brilliant part) pull in all of the user information from every single application in the company into this central database giving them user lists from every application. That user list is then compared to their service desk software (incident tracking stuff) and then all of that information is compared against the employee information from the payroll systems.

With all of the data in a central spot, now, they can issue a simple query on a person, and every application tied to that person is displayed and if their account is active or not. They also flag new hires and terminations and automatically generate tickets in their service desk software to have a help desk person investigate if an account is needed, verify the request for a new account is actually a live person according to payroll, and termination notices no longer have to rely on a manager at some location filling in the proper paperwork and forwarding to the IT department. Now the IT department is aware of the termination and what applications the user had access to and the IT department can now pursue the site to make sure the paper work is filled out.

In the first few weeks they were able to reduce their user count by almost 10% due to duplicate accounts, people that were no longer with the company etc. May not seem like much, but he said it was $20K alone in Novell licensing. Some reports have been put together to give them detailed user counts by application and server for licensing and usage reports.

Very simple idea but yields so much information. Jeremy did it all in APEX and oracle 10gR2 on Linux on an old piece of hardware. I will see if I can get him to put together something technical for this, I can almost smell a business opportunity here.

Good show!

SOA

We have been working on implementing Oracle Fusion middleware for our SOA solution, ESB and BPEL and all the other bells and whistles, BAM and BPA. I have to say, even for an old dog like me, this is an amazing concept. We had IBM and Oracle come and visit numerous times flogging their software and we decided on oracle simply because their products seemed to be more tightly integrated and basically looked better. The kicker was that everything is done via JDeveloper instead of 3 or 4 different products like IBM's SOA stuff (Websphere).

I have built a handful of adapters of some interfaces I know very well. I was able to retrieve data without a problem, I then took a crack at creating ESB and BPEL services to then "listen" for changes and move the data around. All I can say is wow, the ease at which data can be mapped and moved around is astounding. The largest time saving is an adapter only has to be made once per system and then a simple BPEL assign to do the mapping and presto, data acquired, transformed to a common format, and then transformed to what the destination system requires. Then the ESB process sits and waits for more data to come in. Wonderful stuff, no wonder everybody is talking about SOA, even though it is in hushed voices and darkened hallways. The learning curve is extreme and my knowledge of XML,XSD and XSLT has increased a hundred fold, but it is all worth it.

After this I am off to update by CV ;)

We have a few training classes scheduled to try and get the rest of the department some exposure to the products. BPA - Business Process Analyzer I believe is what the acronym is, there are just a few to try and remember. BPA is a product that I have just started to look at, we bought a lot of licenses for it, and as the marketing for it says, it allows business "super users" to actually map the work flow in an almost Visio environment, pass that to a developer and with a lot less work than I expected, the developer can turn that into a BPEL flow and deploy the application. The best part is the changes to the flow the developer needed (if any) are automatically passed back to the user that created the original document.

Really cool stuff.