Blake <blake at kingdomrpg.com> wrote:

> I'm anti-comment, myself, with some rare exceptions. Documenting the class  
> as a whole might make sense, but comments for each method--particularly in  
> Smalltalk--seems, well, redundant.

Wrong, wrong, wrong. Did I say 'wrong'?

Whilst a few small methods might be completely self explanatory as to
what they actually do, it is extremely rare that this is a complete
explanation of what the code is _supposed_ to do. I claim that the
fantasy of 'self commenting code' is just that - a fantasy. Usually
promulgated by lazy buggers that take the attitude summed u in one of
my auto-magic siglines "Comments? Why do you think it's called code?"

Longer methods have exponentially more need for commentary explaining
the intent, known limitations, unfinished parts etc. It's real simple;
stick to Adele's Rule - "if it isn't documented, it doesn't exist" with
the corollary that "and if it doesn't exist, just what did you get paid
for?".  Code is never, ever, written just for you. And even if
579035162 Smith is the only person that ever sees it, s/he is not the
same person in six months time when the original context is forgotten.

If you ever work for me (and ultimately all of you will, sometime) you
will need to provide clear, meaningful comments for just about every
possible bit of code or face Bun-Bun (www.sluggy.com) as punishment.


tim
--
Tim Rowledge, tim at sumeru.stanford.edu, http://sumeru.stanford.edu/tim
"Bother!" said Pooh, as he pulled Piglet out the mincer.