[Seaside] Why seaside really sucks! COMMMMMMMENTS are MISSING

stephane ducasse stephane.ducasse at free.fr
Fri Apr 13 06:53:37 UTC 2007


+1

Stef

On 12 avr. 07, at 21:05, 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].
>
> 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
>>
>
> _______________________________________________
> Seaside mailing list
> Seaside at lists.squeakfoundation.org
> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside
>



More information about the Seaside mailing list