From: Tom Ayerst <twa@...>
Date: 2005-04-27T23:19:27+09:00
Subject: Re: [OT] Comments Are More Important Than Code

This is something of a Straw man argument.  In the article Raskin says:

"I discard the radical position taken by proponents of extreme 
programming (XP) to get rid of 'unnecessary' documentation."

To which you have to ask, "Why would you want to write unnecessary 
documentation? surely you have better things to do, like write necessary 
documentation?".

A more productive debate would not be about the false dichotomy of 
comments vs no-comments but about what comments should be for and what 
level is 'necessary' and what level is 'sufficient'.

Personally I don't document algorithms (unless they are particularly 
obscure) but I try to documemt the responsibility of a classes/modules 
and the intent of methods (unless theyy are so well named it is 
obvious).  Generally I find that this is sufficient; furthermore 
responsibilty and intent change slowly enough that the documentation 
doesn't drift out of line with the code.

Tom

Tim Hunter wrote:
> Even if this is not directly about Ruby, both Jeff Raskin and the 
> subject have come up before on this n.g. so I believe it's not 
> altogether off-topic...
> 
> Comments Are More Important Than Code
> 
> http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290