From: James Britt <james_b@...>
Date: 2005-04-27T23:13:43+09:00
Subject: Re: [OT] Comments Are More Important Than Code

Jim Menard wrote:
> 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
> 
> 
> Yes, but...
> 
> A few days ago, I noticed that a method in the Squeak (Smalltalk) core 
> collection classes did one thing, while its comment said another. That 
> method has probably been around for thirty years or so; the Smalltalk 
> collection classes have a long history.
> 
> Which is correct? The code, because the behavior takes precedence, or 
> the comment, because it expresses the intention?


Ideally, in CDD (comment-driven development), the comments would be 
written first, then the code (including unit tests) written in such a 
way that comments are not needed to describe behavior (though they may 
still be needed to explain design trade-offs or a broader intent).

> 
> I don't know the answer; nobody on the Squeak mailing list has yet 
> responded to my query about whether the code should be changed or the 
> comment.

A problem, but without the comments there may possibly be incorrect code 
with no (obvious) indication that something might be askew.

(One might hope that unit tests would allow the dubious code to be 
changed and tested to see which is correct, the comments or the code.)


James

-- 

http://www.ruby-doc.org
http://www.rubyxml.com
http://catapult.rubyforge.com
http://orbjson.rubyforge.com
http://ooo4r.rubyforge.com
http://www.jamesbritt.com