Comment with parsimony (was something else)

[Alain Farmer]

> Well, back to reality, I guess any language that
> would come close to that ideal would be very
> verbose. In other words, it would be like a regular 
> program that was full of comments!

Self-documenting code does not need to be verbose.
Quite the contrary really. I hate source code that
*submerges* the code with far too many comments. If
your coding std is elegantly simple, without any of
those "really cool" but perversely subtle tricks that
need to be explained, then there is in fact very
little for inline comments. You're far better off
writing a descent technical manual instead. A "best of
both worlds" compromise, proposed by me in the context
of FreeGUI's scriptEditor, would be to make the
comments *collapsable*, e.g. only see them when you
want to see them + instantaneous switch betwwen the
two whenever you want. Or, really wild, would be to
make them criteria/profile based. IOW, comments
according to who you are (experience level, prefs) and
the task you are currently attempting to accomplish
(learn the code, debug the code, etc).

You might be thinking that I am a rare bird who
doesn't conform to traditional ways of programming &
commenting that we learned at school. This is true,
but I am not as rare as you might think. There are a
dozen+ new "agile" software development methodologies
being taught & used, like "Extreme Programming" for
ex, which argue against too much documentation and
"big-design-up-front". They create a lot of
un-necessary weight which then has to be shouldered
and constantly updated throughout the process and
almost never in synch anyway. Being "agile", nimble,
quick to adapt to change/uncertainty, even *embracing*
them, that's what makes a development team innovative
& effective.

In essence, you should be as parsimonious as you can
be with your comments, relying instead on the dev's
group abilities, the quality of their communication,
and their adherence to a rational *coding standard*
established by them for them. This may sound a bit
*wacky* to those of you brought up in the traditional
way, particularly if this woefully un-detailed account
of why commenting is not as good/important as we've
been brought up to think is your only exposure to this
radical idea, but I am far being alone in this
"different thinking". For more info, enter the
following words into your favorite web search engin :
Extreme Programming, XP, Refactoring, Agile ...

Rebelliously yours,

Alain Farmer

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