Why seaside really sucks! COMMMMMMMENTS are MISSING

> Yea, I figured it had to do with "live objects" and everything.  I just
> find it a bit distracting (like as in, when you go to the theater and
> they put in about 3 more previews then normal before your movie), but
> it's not a big deal.
>
> tim Rowledge wrote:
>>
>> On 12-Apr-07, at 12:05 PM, Jason Johnson wrote:
>>
>>>
>>> And what is with the first person commenting?  For me it doesn't add
>>> anything but typing/reading, with no value add.
>>>
>>> "I am the method responsible for rendering the class..."
>> The tendency to first person comments stems from the anthropomorphic
>> viewpoint of being inside an object.
>>
>> tim
>> --
>> tim Rowledge; [hidden email]; http://www.rowledge.org/tim
>> Useful Latin Phrases:- Die dulci fruere = Have a nice day
>>
>>
>> _______________________________________________
>> Seaside mailing list
>> [hidden email]
>> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>

> 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].
>
> And what is with the first person commenting?  For me it doesn't  
> add anything but typing/reading, with no value add.
>
> "I am the method responsible for rendering the class..."
>
> vs.
>
> "responsible for rendering the class..."
>
> Just my $ .02,
> Jason
>
> [1]  Of course the exception to this would be Javadoc style auto  
> generated documentation, but that stuff is generally just for  
> presenting the interface of a system and thus makes me wonder if  
> the tests wouldn't be a better source for it.
>
> stephane ducasse wrote:
>>
>> On 6 avr. 07, at 21:01, Boris Popov wrote:
>>
>>> Silly question, what is it you expect commented? Methods?
>> "I'm a cool method that does that and that my subclasses should  
>> redefine"...
>>
>> "I'm private method doing that. But please do not override me  
>> instead specialize...."
>>
>>> Classes?
>> for each class (important)
>> I want to have
>>     my goal
>>     my responsibility
>>     my collaborators
>>     my extensions hook
>>         may be link to examples
>>     Personally I do not care about my iv is a String.
>>
>>> Packages? Would we be better off with documentation instead?
>> May be also at the package level.
>>
>>> If I were looking for a way to configure select list with a  
>>> labels block, where would I expect to find a comment for it?
>>
>> In a brush class comments and in the examples on the class side.
>>> Look at every method in there until I see one with matching  
>>> comment? No offence, just trying to see how I could help out, not  
>>> once have I thought in the past year, jee I wish this was  
>>> commented, because by the time you find what you're looking for,  
>>> comment within it is a little late :)
>>
>> but commenting is not for people knowing :)
>>
>> Stef
>>>
>>>
>>> Cheers!
>>>
>>> -Boris
>>> (Sent from a BlackBerry)
>>>
>>> ----- Original Message -----
>>> From: [hidden email] <seaside-
>>> [hidden email]>
>>> To: Seaside - general discussion  
>>> <[hidden email]>
>>> Sent: Fri Apr 06 11:53:47 2007
>>> Subject: Re: [Seaside] Why seaside really sucks! COMMMMMMMENTS  
>>> are MISSING
>>>
>>> 2007/4/6, Rick Flower <[hidden email]>:
>>> > Philippe Marschall wrote:
>>> > > Commit them, they will get reviewed and if accepted merged.
>>> > Can I assume that this must be done in the squeak environment  
>>> and that
>>> > it might be extra work
>>> > to do this if you're using VW or other non-squeak dialects of  
>>> ST -- correct?
>>>
>>> Must is quite a strong word. I'm sure we would also accept change  
>>> sets
>>> posted to the mailing list or mantis.
>>>
>>> Philippe
>>>
>>> > Too bad VW can't talk directly to the Squeak repository too..
>>> >
>>> > _______________________________________________
>>> > Seaside mailing list
>>> > [hidden email]
>>> > http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>> >
>>> _______________________________________________
>>> Seaside mailing list
>>> [hidden email]
>>> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>>
>>> _______________________________________________
>>> Seaside mailing list
>>> [hidden email]
>>> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>
>> _______________________________________________
>> Seaside mailing list
>> [hidden email]
>> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>
>
> _______________________________________________
> Seaside mailing list
> [hidden email]
> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside

> 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].
>
> And what is with the first person commenting?  For me it doesn't  
> add anything but typing/reading, with no value add.
>
> "I am the method responsible for rendering the class..."
>
> vs.
>
> "responsible for rendering the class..."
>
> Just my $ .02,
> Jason
>
> [1]  Of course the exception to this would be Javadoc style auto  
> generated documentation, but that stuff is generally just for  
> presenting the interface of a system and thus makes me wonder if  
> the tests wouldn't be a better source for it.
>
> stephane ducasse wrote:
>>
>> On 6 avr. 07, at 21:01, Boris Popov wrote:
>>
>>> Silly question, what is it you expect commented? Methods?
>> "I'm a cool method that does that and that my subclasses should  
>> redefine"...
>>
>> "I'm private method doing that. But please do not override me  
>> instead specialize...."
>>
>>> Classes?
>> for each class (important)
>> I want to have
>>     my goal
>>     my responsibility
>>     my collaborators
>>     my extensions hook
>>         may be link to examples
>>     Personally I do not care about my iv is a String.
>>
>>> Packages? Would we be better off with documentation instead?
>> May be also at the package level.
>>
>>> If I were looking for a way to configure select list with a  
>>> labels block, where would I expect to find a comment for it?
>>
>> In a brush class comments and in the examples on the class side.
>>> Look at every method in there until I see one with matching  
>>> comment? No offence, just trying to see how I could help out, not  
>>> once have I thought in the past year, jee I wish this was  
>>> commented, because by the time you find what you're looking for,  
>>> comment within it is a little late :)
>>
>> but commenting is not for people knowing :)
>>
>> Stef
>>>
>>>
>>> Cheers!
>>>
>>> -Boris
>>> (Sent from a BlackBerry)
>>>
>>> ----- Original Message -----
>>> From: [hidden email] <seaside-
>>> [hidden email]>
>>> To: Seaside - general discussion  
>>> <[hidden email]>
>>> Sent: Fri Apr 06 11:53:47 2007
>>> Subject: Re: [Seaside] Why seaside really sucks! COMMMMMMMENTS  
>>> are MISSING
>>>
>>> 2007/4/6, Rick Flower <[hidden email]>:
>>> > Philippe Marschall wrote:
>>> > > Commit them, they will get reviewed and if accepted merged.
>>> > Can I assume that this must be done in the squeak environment  
>>> and that
>>> > it might be extra work
>>> > to do this if you're using VW or other non-squeak dialects of  
>>> ST -- correct?
>>>
>>> Must is quite a strong word. I'm sure we would also accept change  
>>> sets
>>> posted to the mailing list or mantis.
>>>
>>> Philippe
>>>
>>> > Too bad VW can't talk directly to the Squeak repository too..
>>> >
>>> > _______________________________________________
>>> > Seaside mailing list
>>> > [hidden email]
>>> > http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>> >
>>> _______________________________________________
>>> Seaside mailing list
>>> [hidden email]
>>> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>>
>>> _______________________________________________
>>> Seaside mailing list
>>> [hidden email]
>>> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>
>> _______________________________________________
>> Seaside mailing list
>> [hidden email]
>> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>
>
> _______________________________________________
> Seaside mailing list
> [hidden email]
> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>

> 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
> [hidden email]
> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>

> 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.

>
> 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
> [hidden email]
> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>

> Comments should also tell about implicit conventions.
> Remember my post on squeak dev about morphic heading
>
> I do not know the unit (degrees radians ?)
> I do not know the origin (toward upscreen, right ?)
> I do not know direction (clockwise, counter clockwise ?)
>
> Reverse engineering the code is not the fastest way to the information...
>
> As for the first person, remember objects know about themselves, this
> is called reflexivity (self = ego = I).
>
> Nicolas

> I'm more interested in class comments - the architectural view.
>
> Example: WAController - OK what does it control?  How does it fit with
> WARequest, WAResponse and the rest of it?  I haven't a clue.  
> Actually, I think this class went away in later versions (I'm still on
> an older version of seaside) but still, I had a lot of trouble getting
> the point of this class.
>
> -Todd Blanchard
>

> -----Original Message-----
> From: [hidden email] [mailto:seaside-
> [hidden email]] On Behalf Of Jason Johnson
> Sent: Friday, April 13, 2007 10:12 AM
> To: Seaside - general discussion
> Subject: Re: [Seaside] Re: Why seaside really sucks! COMMMMMMMENTS are
> MISSING
>
> nicolas cellier wrote:
> > Comments should also tell about implicit conventions.
> > Remember my post on squeak dev about morphic heading
> >
> > I do not know the unit (degrees radians ?)
> > I do not know the origin (toward upscreen, right ?)
> > I do not know direction (clockwise, counter clockwise ?)
> >
> > Reverse engineering the code is not the fastest way to the
> information...
> >
> > As for the first person, remember objects know about themselves,

>> I agree.  I would expect every class to have a comment
>> (unless the classes are clearly a very specialized subclass
>> with a name expressive enough that you understand).  For me,
>> that's why they have a comment pane and a red "No comment!"
>> message. :) _______________________________________________
>>    
>
> Or at least, all the classes at the root of the family.  Just understanding
> how all the abstract classes work together and how they're expected to be
> specialized in subclasses goes a long way in groking a framework.