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

[Jason Johnson]

Andreas Raab wrote:
> 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.
Yes, a short to the point comment like that in something that takes some 
thought like recursion is a good idea.  I'm just talking about when 
someone writes huge books for every method, complete with fancy ASCII 
art headers and such (for every method!).  Of course, that kind of brain 
dead practice is much more common in other languages, but I figured I 
would throw it out there since no one else did. :)

> 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" ;-)
Well, it's not my opinion that if you can't understand my code you're an 
idiot.  It is more my opinion that if you can't read my code then I need 
to write clearer code (that is, it's an insult to me not you).  Some 
comments save time, but we have other things that save time as well 
(e.g. method categories).
> 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.
Again, I was talking about the cost of having to *read through the 
comments*.  I wasn't thinking about time spent writing the comments at 
all.  Seaside for sure needs to have some obvious documentation of what 
the interfaces are, methods people would be interested in, what they 
never would look at and so on.  And much of this can be helped by a 
method categorizing convention (i.e. certain categories are always 
interface, some always private/volatile/experimental/etc.).
>
> 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
>