> It would have taken the original author maybe 10 minutes to explain what he
> was up to in those 20 lines.  It would have saved me a week.

Did you ever hear the story of the lady who had a squeaky floor?  She
couldn't get the floor to stop squeaking so she hired a handyman and
he came out, walked around the floor for a few minutes, stooped over
and drove a single penny nail into the floor. The squeak was gone!

He said that it would be $100 for the repair.  The lady, in shock,
asked that he itemize the repair.  So the handyman wrote out an
itemized bill:  $1 - penny nail; $99 - know where to put it.

So how long did it really take to find those 20 lines of code where
the problem was probably located?

Bear with me as I step on the soap box for a minute.  I am an IT
manager and also developer.  I've seen exactly the situation described
here, occur before, but let me chime in with my 2 cents.

First, I think if it is not too much trouble I would encourage any
developer of mine (or myself) to comment their code appropriately.

Secondly, it is *always* too much trouble (whether appropriate or not).

Finally, (now here's my soap box), you will always find that code
picked up by someone else who has not seen nor operated on the code
before to *always* take a long time vs. the guy (or gal) who was
highly skilled in that arena.  I don't care if you have well
documented software or not.  I don't care if you have good UML
diagrams either.

Just look at the API for a commercial grid and tell me you can jump
into it and be effective in short order.  Good luck -- even with the
pounds of API documentation.  (Consider yourself lucky if you haven't
had to tackle one of these beasts).

I believe that you just cannot expect a large body of functionality to
be immediately understandable by someone who has not seen the code
before (esp. in a hostile "fix the bug now" environment).

Crummy code can make the task nearly impossible, and clean code that
is absent many common "code smells", at least, tractable.  (I wouldn't
consider the lack of comments a "code smell").

Professionally, I find the best way to facilitate a shared
understanding of the code is to not wait until the last minute to get
other developers involved in the code base. To the extent that this
can be done, I think the code quality greatly increases and the need
for extra documentation can be greatly diminished.

Regards,

John

-- 
If at first the idea is not absurd, then there is no hope for it. --
Albert Einstein