[Seaside] Re: Why seaside really sucks! COMMMMMMMENTS are MISSING
andreas.raab at gmx.de
Fri Apr 13 06:52:35 UTC 2007
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?) .
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:
"Evaluate aBlock recursively with the receiver and its children"
aBlock value: self.
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
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.
More information about the Seaside