Imagine walking into a library, and having to walk up and down the aisles trying to find the book you want. You may find the book eventually, or you may not. One thing is for sure it would take you a long time. If it takes you too long, most probably you’ll end up walking away without the book you were looking for.
Imagine walking into a hardware store, one of those big ones that is the size of a warehouse, full of tools, row upon row and shelf upon shelf. But nobody has put any signs up. So you walk down the aisles looking for the tool you need. Chances are if you do not find the one you want you will just walk away and find a different solution to the problem you needed the tool to fix.
The other day I was talking to my friend Lee. We were trying to solve a problem in one of the products that we maintain. It doesn’t matter what the problem was, but we were both convinced that there was already a library to solve the problem.
But we couldn’t find it. The library must have been buried somewhere deep amongst the tens of thousands of lines of code we have.
So we had to re-write the code to fix the problem.
A few days later another one of my work friends, Tay, came up to me and asked why we had written a new code library for functionality that already existed? I replied that we knew there was a library but that we couldn’t find it.
“Oh”, replied Tay, “What you need to do is look at the code index I have been building”
“Wha?”, I looked at Tay blankly.
“Well” continued Tay, “Everytime I make a change to a library function I make sure I add the appropriate documentation comments and then run the automatic documentor over it. Then I copy the generated docs to our departmental share. I sent an email around about it a few weeks back, didn’t you see it?”
“Errr, no” said I “Where is it? I’ll go and take a look now”!.
Do you document your code libraries and keep an index? I would love to know so why not leave a comment.