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

Boris Popov boris at deepcovelabs.com
Fri Apr 13 17:21:18 UTC 2007


For me, the whole thing about comments is very simple. I use Prototype
almost exclusively for most scripting here. Do I ever look at the source
code? Yes, on occasion. Do I look at it to figure out how to use it? No,
because there's http://www.prototypejs.org/api instead.

Let's figure out a good model for creating simple straightforward
documentation similar to that one and invite contributions. I know I
could spend few minutes every week writing up comments and examples and
if all of us did it, we'd have decent documentation in no time.

Cheers!

-Boris

-- 
+1.604.689.0322
DeepCove Labs Ltd.
4th floor 595 Howe Street
Vancouver, Canada V6C 2T5
http://tinyurl.com/r7uw4

boris at deepcovelabs.com

CONFIDENTIALITY NOTICE

This email is intended only for the persons named in the message
header. Unless otherwise indicated, it contains information that is
private and confidential. If you have received it in error, please
notify the sender and delete the entire message including any
attachments.

Thank you.

> -----Original Message-----
> From: seaside-bounces at lists.squeakfoundation.org [mailto:seaside-
> bounces at lists.squeakfoundation.org] 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,
this
> > is called reflexivity (self = ego = I).
> >
> > Nicolas
> Yes, those are good things that need to be documented.  And no, one
> shouldn't have to dig through source to find out what a method is
called
> with.  I'm not against documentation and I'm not against comments.
But
> I mean, just because something is a comment doesn't mean it is good.
It
> is possible to write bad comments as well (e.g. commenting every line
> telling what that line does.  We're not coding in assembler after
all).
> 
> So to phrase it another way:  Good comments are good, bad comments are
> bad. :)
> _______________________________________________
> Seaside mailing list
> Seaside at lists.squeakfoundation.org
> http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside


More information about the Seaside mailing list