goran.krampe at bluefish.se wrote:
> "Lex Spoon" <lex at cc.gatech.edu> wrote:
> > Interesting idea, but IMHO no.  I don't even quite agree that every
> > class needs a comment; if you see this class hierarchy:
> > 
> > 	LambdaExpression
> > 		LEVariable
> > 		LEApplication
> > 		LEAbstraction
> > 		
> > Then it is utterly pointless to go through putting comments like "a
> > LEVariable is a lambda expression variable" and "a LEApplication is a
> > lambda expression application".  If you know what a lambda expression
> > then you don't want a comment in the subclasses.
> 
> How can you say "don't want a comment"? Are they somehow hurting you?
> Btw, I remember I think what a LambdaExpression is, though I wouldn't
> off hand know what the hell an LEApplication is compared to an
> LEAbstraction. Why not give me a hand and telling me in the class
> comment?

Yes, they hurt, though not much.  Here are a few ways:

	1. They are extra maintenance.  Any change to those classes must now
modify the comments, too, to keep up.

	2. They are an extra source of bugs.  Wrong comments are bad.
	
	3. They easily duplicate effort.  It is better to comment things in one
place and where necessary to have links to that one place.
	
	
BTW, I intentionally picked an obscure example.  The point is that you
if you don't know what a lambda expression is then you have no hope of
dealing with a l.e. "abstraction".  Thus you really need to go read the
LambaExpression comment, first.


Let me step back and mention two perspectives I am coming from.

First, I view reading a Smalltalk program as an exploration.  The
programmer knows certain things, and they probe into the system to learn
ever more.  There are many different ways to probe into the system, and
I try to keep this in mind when I write code.  I do not expect any
individual part of the code to document the entirity; the code is itself
a document.

In this particular example, I would expect people who are looking at a
class deep within a hierarchy, to take a peek at the superclasses in
order to orient themselves.   This is so automatic that I don't think
every subclass in the system should even need a specific link mentioned
in the comments.  Do we really want, for example, every subclass of
Morph to say "see the Morph superclass for more info" ?  IMHO, such a
comment is just as wasted as this one:

	x := x + 1.   "add 1 to x"	
	
	
Second, any rules cause some chaffing.  I have been watching Debian
amass larger and larger piles of policy, and it saddens me.  I *like*
having individuals use their own taste, and I like having the freedom to
explore my own style.  Every rule cuts away style possibilities, however
small they may seem.   Further, every rule, no matter how innocuous it
appears, is a chance to get it horribly wrong and thus end up very
annoying to lots of people.  Thus I have a general tendency to avoid
global rules as much as we can.


	
Doug Way <dway at mailcan.com> wrote:
> Sort of making up a figure here, but I'd say 98% of all classes in the 
> base release need to have class comments.  Given that, I think it would 
> be reasonable to enforce that all new base release classes have to have 
> class comments, even if it means that the 2% of classes which don't 
> really need them have to have them too.

Yes, it's probably a fine tradeoff to insist on every class having a
comment, even when useless.  I'd guess it is actually less than 2%, even
for me, that are better off without a particular comment.


-Lex