[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