no flames felt, cool as the other side of the pillow

[Sadhunathan Nadesan]

| Last but not least, my zealous dismissal of commenting
| and documentation was a little bit overstated. I still
| cling to them too, but since I'm in a XP group that
| down plays the importance of comments, I thought it
| might be interesting to play "Devil's Advocate" on
| this issue to shake up people's 'certainties'. It was
| NOT my intention to flame you in any way, and I beg
| for your forgiveness if you feel that I have flamed
| you in any way.
| 

Alain,

I didn't feel that way at all.  Everything you said
was presented very respectfully.  So not to worry!
But thank you for being such a gentleman.

Sadhu


ps - I had an interesting experience yesterday.  I had to investigate
if there was an existing mechanism in our payroll gross to net module
(a mere 10,000 lines of code, rather undercommented IMO) to tax people
on life insurance policies over $50k. The IRS says that if your company
pays for a policy for you, although you do not get any actual cash,
that is employee compensation and the equivalent value of the premium
(depending on your age, etc), has to be taxed, so you owe a few more
cents FICA (not FUTA).  Ok so I am pouring through information trying
to find out about this.  I found enough clues to lead me to where to
look in the code base.  It was not obvious though.

I found the subroutine.  Very few comments.  At least there were some!
Lucky thing the guy who wrote it 5 years ago is still here.  He absolutely
disclaimed any knowledge of it, said he had never seen it, etc, but
RCS proved it was his code.  It was actually beautifully and clearly
written, nice long variable names etc.  You might think (at the time
you were writing it or QA'ing it) that it was almost self explanatory.
It was paired down, clean, refactored or whatever you want to call it.
However, I didn't understand it and, he didn't understand it either.
Not enough comments.  We stared at it a while and it didn't make sense.

So we had to sit there tracing through it with the debugger to watch
what it was doing to back into the logic behind the formulas, and sort
of reverse engineer what was the thinking 5 years ago. Of course this
time around we wrote that all down, to prevent this problem next time.

Obviously after spending WAY too many hours on this research I am more
eager than ever for my programmers to use more comments.

I'm thinking maybe, hyperlinks to external pages of comments, or vi tags.