[Seaside] Re: Why seaside really sucks! COMMMMMMMENTS are MISSING

[Andreas Raab]

Jason Johnson wrote:
> I'm surprised to be saying this, but one must not forget that commenting 
> also has a cost.  My current rule is that a comment shouldn't say what 
> something does.  If the code is so unclear that it would need such a 
> comment it should be rewritten (obviously if you're doing optimized code 
> this rule has to be relaxed a bit).  Comments should say what the code 
> doesn't (e.g. why was it done this way?  Are there some non-obvious 
> dependencies here?) [1].

I disagree. Comments should introduce you to the code. If they restate 
the obvious that's fine, all it means is that the person reading it has 
an extra chance to understand what is going on (because what is obvious 
and what not depends on the *reader* not the writer of the comment). In 
addition, a well-written comment is *always* easier to understand even 
if the code is obvious. I find this over and over again; if I see a 
method that says, for example:

TFrame>>allFramesDo: aBlock
   "Evaluate aBlock recursively with the receiver and its children"
   aBlock value: self.
   frameChildren ifNotNil:[
     frameChildren do:[:fc| fc allFramesDo: aBlock].
   ].

the comment says everything there is to it and reading it takes me 
roughly a second or two. Reading and understanding the code probably 
takes me 5 seconds, even when I'm familiar with the underlying code 
base. In situations where I am not (like Seaside) it takes 
*significantly* longer.

Also, in general I've come to consider writing a comment a sign of basic 
politeness. It means: "Hey, reader, you are welcome here, I wrote a 
comment for you because I *want* you to understand what is going on 
here", contrasted with the attitude that "well if you can't tell from 
the code, you're probably not smart enough to understand anything here 
anyways, so why don't you go and use Visual Basic instead" ;-)

And finally, writing the comment is a cost imposed once. Having written 
it once, you reap the benefits *every single time* someone looks at this 
code. Which, to me, is reason enough why frameworks like Seaside should 
have lots and lots of comments - the cost/benefit ratio is clearly on 
the side of writing more comments rather than less since frameworks have 
lots of people looking at the code.

And I'm not saying I am perfect at writing comments (as some people 
would quickly point out to you ;-) and I am not saying that *every* 
method must have a comment. But I will say that -unless a comment is 
just plain wrong- no method or class is be better off without a comment 
than with a comment.

Cheers,
   - Andreas