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
>