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