Commenting

[Alain Farmer]

Hello Sadhunathan and y'all,

> Yes, I agree, code cluttered with too many comments
> looks messy and it's hard to find what you are
> looking for. One line of comments per 10 lines of
> code may be enough. The problem comes in when there 
> are no technical docs or no comments, nada ... I am 
> talking about programs in the 2,000 to 10,000 lines
> of code range, not your simpler 100-500 line
program.
> Everything needs to be in the context of scale. I am

> talking about enterprise applications with a million

> plus lines of code like the ones I'm responsible
for,
> composed of many hundreds of individual programs and
> interacting systems. It is absolutely unthinkable
not 
> to have comments plus companion technical docs.

Good point, Sadu. Larger projects with millions of
lines of code, many *hundreds* of programmers, are too
large and un-manageable for most "agile"
methodologies. Kent Beck and others do address this
"scaling-up" issue with some other "agile"
methodologies, but I am not going to belabour this
point. OTC, I want to stress that you are right about
*HUGE* projects requiring a lot more formal structure
and procedures. Add to that the HUGE amounts of money
and time sunk into such projects -> commenting and
docs become essential, un-avoidable, etc. So now the
issue becomes : How much comments/docs are good/bad
for projects that are less-than-HUGE, e.g. small,
medium or large projects; say with less than dozen
team members.

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.

Respectfully,

Alain Farmer

__________________________________
Do you Yahoo!?
The New Yahoo! Search - Faster. Easier. Bingo.
http://search.yahoo.com