From: Ara.T.Howard@...
Date: 2005-04-27T23:24:27+09:00
Subject: Re: [OT] Comments Are More Important Than Code

On Wed, 27 Apr 2005, 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?
>
> 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.

amen.  i've always felt that the whole comment thing breaks down in two ways:

   - syncing, which you're showing here

   - ambiguity : english (any human lang) is ambiguous - code is not.
     obfusicated mabye, but ambiguous no.

not that comments are a bad thing - but the source is the authority so, if you
can read it, why look elsewhere?  i think that, as languages become more and
more VHL we'll see less and less commenting - i already feel that it's __ok__
(though not ideal) to not doccument a small to medium bit of ruby intended for
developers since, in that specific case, the end users can get the most
accurate view of the code from the code itself whereas in the case of say, the
gnu scientific library written in reams of c, doccumentation is essential.  i
think discussions of the merits of comments must be framed within a specific
computer language since that computer language can contribute or detract from
any meaning conveyed by english (or other) docs.

2cts.

-a
-- 
===============================================================================
| email   :: ara [dot] t [dot] howard [at] noaa [dot] gov
| phone   :: 303.497.6469
| although gold dust is precious, when it gets in your eyes, it obstructs
| your vision. --hsi-tang
===============================================================================