[Seaside] Why seaside really sucks! COMMMMMMMENTS are MISSING

[Jason Johnson]

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: seaside-bounces at lists.squeakfoundation.org 
>> <seaside-bounces at lists.squeakfoundation.org>
>> To: Seaside - general discussion <seaside at lists.squeakfoundation.org>
>> Sent: Fri Apr 06 11:53:47 2007
>> Subject: Re: [Seaside] Why seaside really sucks! COMMMMMMMENTS are 
>> MISSING
>>
>> 2007/4/6, Rick Flower <rickf at ca-flower.com>:
>> > 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
>> > Seaside at lists.squeakfoundation.org
>> > http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>> >
>> _______________________________________________
>> Seaside mailing list
>> Seaside at lists.squeakfoundation.org
>> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>>
>> _______________________________________________
>> Seaside mailing list
>> Seaside at lists.squeakfoundation.org
>> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>
> _______________________________________________
> Seaside mailing list
> Seaside at lists.squeakfoundation.org
> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>