Ale,

I agree, but I feel that we should possibly go even further. Smalltalk 
defines a language, its defined words are class names and message 
selectors. The current practice makes every class into a separate dialect 
that may or may not be similar to some other dialect.

Smalltalk would be easier to read if we made interfaces into first class 
citizens. A selector would then mean the same everywhere that interface was 
used. Smalltalk would be harder to write because I would have to be 
consistent and to invent good names that preferably didn't conflict too 
badly with prior uses. And yes, it would be important to comment the 
selectors; methods would only be commented if there was something special 
in the implementation.

I feel interfaces will be essential in the context of my IS21c project and 
probably also Jacaranda.

--Trygve



At 03.03.2004 08:29, you wrote:

>Hi All,
>
> > With methods, I expect the reverse: the majority of methods should *not*
> > have a comment.  I find that with a good class comment and with good
> > general documentation of what is going on, that the  meaning of most
> > individual methods are quite obvious.
>
>Please, can we distinguish between method and message comments?
>For example in the method:
>
>! MyClass methodsFor: 'aditions'!
>add: anObject
>     "Add anObject to the receiver."
>
>     ^myContents addLast: anObject ! !
>
>The "Comment" here is the comment of the MESSAGE.
>Not the comment of the method.
>
>Message comments MUST be the same in all environment
>  and must be mantained as a part of the message.
>A message has a name(aSelector), argument names, and a Comment.
>
>All classes that implements the message #add:
>  must use anObject as the argument and the SAME comment.
>
>Why the same selector? (it is clear why)
>Why the same argument names? - Because if there is any restriction in the
>arguments semantics, it must be treated as another message (no
>polimorphism).
>Why the same comment? - because the comment of the message MUST define the
>semantics of the MESSAGE and no any local detail of implementation.
>
>What about method(code) comments?
>I this that code comments are not necesary
>  for the smalltalker, because the methods must
>  not be long enough to be explained.
>
>I think that class comments are very powerfull for documenting,
>  but ony refer to object level descriptions.
>It can be very interesting to have any posibility to document
>  frameworks e.g. comments for class categories.
>The use of morphs for documenting can be very interesting
>Embedding multimedia comments in chunk format
>  can result in loosing readability of sources...
>  how can we solve this?
>
>What do you think about attaching comments to softare elements?
>  and mantain them by a comment tool?
>
>cheers,
>Ale.
>
>
>----- Original Message -----
>From: "Lex Spoon" <lex at cc.gatech.edu>
>To: "The general-purpose Squeak developers list" <squeak-dev at lists.squeakfou
>ndation.org>
>Sent: Wednesday, March 03, 2004 3:04 AM
>Subject: Re: Back to the issue... (was RE: Squeak coding style...)
>
>
> > tim Rowledge <tim at sumeru.stanford.edu> wrote:
> > > > LargeInteger
> > > > LargePositiveInteger
> > > > LargeNegativeInteger
> > > >
> > > > Sure, put a comment in LargeInteger to say what "large" means.  But a
> > > > comment would be useless in the two subclasses.
> > > I disagree, obviously given my above comments.
> > > LPI should becommented to explain that it represents only positive
> > > values, that the code may need to create LNIs as a result of
> > > subtractions, that normalisation may produce SmallIntegers(we recently
> > > had list messages relating to some confusion about this).
> > > LNI would benefit from explanations of a similar nature but obviously
> > > LPIs are created asa result of -ve * -ve and all that.
> >
> > These are important things to document, but almost all of them should be
> > in the superclass LargeInteger.  The only new information that is in LPI
> > or LNI is "positive" or "negative", plus possibly "see the superclass".
> > It is not a bad thing if such simple comments are left out entirely.
> >
> > Here's a better example: class HtmlEntity, which has a subclass for each
> > HTML tag.  Does HtmlImage really need to have a comment like "HtmlImage
> > is for <image> entities" ?  That seems wasteful to me.  To understand
> > HtmlImage you need to understand its superclass; once you understand its
> > superclass, no comment is necessary.  HtmlImage is no more and no less
> > than what it's name suggests: an entity for images.
> >
> > I don't think this kind of class is at all common, but it does come up
> > occasionally.  Some classes do not need comments.
> >
> > With methods, I expect the reverse: the majority of methods should *not*
> > have a comment.  I find that with a good class comment and with good
> > general documentation of what is going on, that the  meaning of most
> > individual methods are quite obvious. For example, once you understand
> > what, generally, a Morph is about, then you don't need to explain what
> > #width is.  The name says it all and an extra comment will not help.
> >
> > For amusement, I just looked at the 13 implementors-of #width.  10 have
> > no comment, of which at least 9 do not need a comment (I can't evaluate
> > the 10th without learning more about the class first).  1 implementor,
> > in DisplayObject, has a good, helpful comment.  1 implementor simply
> > says "for compatibility".  And to round it out, Rectangle's
> > implementator has a classic wasted comment: "Answer the width of the
> > receiver".  IMHO this is all ideal except for Rectangle's method
> > comment, which should be removed.
> >
> >
> > -Lex
> >


-- 

Trygve Reenskaug      mailto: trygver at ifi.uio.no
Morgedalsvn. 5A       http://heim.ifi.uio.no/~trygver
N-0378 Oslo           Tel: (+47) 22 49 57 27
Norway