Agile Zone is brought to you in partnership with:

I wrote my first program in Z80A when I was 14 on a ZX Spectrum and ever since I have been hooked. I love writing code of any flavour as well as being passionate about the coding process. I have worked professionally in the software industry for the last 15 years using Microsoft Technologies, and I code at night in PHP, HTML, Javascript and CSS. Chris is a DZone MVB and is not an employee of DZone and has posted 34 posts at DZone. You can read more from them at their website. View Full User Profile

Every Library Needs an Index

  • submit to reddit

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.

Published at DZone with permission of Chris Odell, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)