From: Jim Menard <jimm@...>
Date: 2005-04-30T21:33:55+09:00
Subject: Re: Comments Are More Important Than Code


On Apr 29, 2005, at 7:40 PM, Pete Elmore wrote:

> Dave Fayram wrote:
>> On 4/29/05, Lorenzo Jorquera <lorenzo_jorquera@yahoo.com> wrote:
>>> Comments tell you what the code *SHOULD* be doing, not *WHAT* it is
>>> doing. So many people responding to this thread seem oblivious to 
>>> this
>>> obvious, yet subtle and important fact.
>
>> Please try not to confuse your preferred development philosophy with
>> fact. It isn't good for this discussion. The fact that we can even
>> have such a heated debate over comments should tell you that no one
>> here is 100% right.
>
> I don't think he's talking about development philosophy; it looks like 
> what he's saying is "Comments tell you what the programmer thinks the 
> code is doing, not necessarily what the code is actually doing.", 
> which actually is a fact.

No, it's not. Comments tell you what the programmer thought the code 
should be doing when he wrote the comment. Not all programmers keep the 
comments and code synchronized.

> It's an almost cliche saying among coders that the computer will do 
> exactly what you tell it, not what you think you tell it.  The 
> comments document what the programmer thinks he told the computer.

...at the time he wrote or last modified the comment.

Jim
-- 
Jim Menard, jimm@io.com, http://www.io.com/~jimm/
"The theory of computation states that all automatons can be emulated
by a Turing machine. I have a less abstract but more practical motto: If
you can do it on Intel, you can do it damn near anywhere!"
     -- Eugene O'Neil