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

stephane ducasse stephane.ducasse at free.fr
Fri Apr 13 16:36:43 UTC 2007


+1
On 13 avr. 07, at 08:52, Andreas Raab wrote:

> 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
> _______________________________________________
> Seaside mailing list
> Seaside at lists.squeakfoundation.org
> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>



More information about the Seaside mailing list