I'm rather new to the list, however I am a foot soldier of the computer 
revolution from WAAYY back.

My wife and I often joke that you only need to watch one episode of a 
soap opera per year in order to stay abreast of the plot line. I'll now 
have to add "or read one programming language thread" to the list.

Commenting of code is an idea that I believe is fundamentally broken, 
not because I think code should be un-commented or self-commenting. 
Rather, I believe that our implementation of the idea is broken.

"Do comments really belong in the code body?"

The purpose of writing code is to create behavior. Effective code runs 
reliably, and eventually sinks down into the infrastructure where it's 
operation is taken for granted. (Is this similar to the "ancient 
preserved sequences in DNA?) As well, code tends to be re-used.

I offer that it is the use of the code to effect a change of state that 
best describes the CURRENT value and meaning of that body of code. With 
time and additional re-use, the meaning and utility of a block of code; 
whether a module, class or method, changes. Should we therefore require 
that information relevant to that code be co-resident in the same body 
of text?

My personal answer is "No". The information about intent, meaning and 
value of a body of code should be captured in the context of it's 
usage. Fundamentally, it should be captured in it's design 
specification.

Our failure as I see it is a lack of design for our design. We use our 
objects to model the objects and behaviors of our world, perhaps we 
need a parallel mechanism to model our knowledge of that world?

Very best regards,
Roy


On Sunday, Oct 17, 2004, at 22:17 America/Vancouver, Richard A. O'Keefe 
wrote:

> Bernhard Pieber <bernhard at pieber.com> wrote:
> 	- Comments are a form of redundancy.
>
> It seems to me that this is the heart of his argument.
>
> I deny it.  What I always tell me students is
>
>     "Comments should tell the reader what s/he needs to know
>      that ISN'T there in the code."
>
> The topic of this thread is class comments, and they are by no means
> redundant.  When written by someone with even half a brain, they tell
> me things I need to know that are NOT obvious from the code.
> And that's why we need them.
>
>