"Lex Spoon" <lex at cc.gatech.edu> wrote:
> 
> > Perhaps this should be expanded so that uncommented methods (perhaps 
> > testing for more than a smallish number of bytecodes?) also have such a 
> > comment automagically added? Since we have the writers initials 
> > (normally) we could even make it be something like
> > 
> 
> 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?

>  The name suffices.  Or
> how about this one:
> 
> 	LargeInteger
> 		LargePositiveInteger
> 		LargeNegativeInteger
> 		
> Sure, put a comment in LargeInteger to say what "large" means.  But a
> comment would be useless in the two subclasses.

First of all this is not how those classes look - but I assume it is
hypothetical.
Furthermore I find the class comments of the existing classes to be
perfectly fine - the one in LargeNegativeInteger tells me that "there is
nothing special to know here, move on please". Perfect.

Still it would be interesting to know for example if an instance of
LargePositiveInteger is identical to a LargeNegativeInteger except for
its class - which it is btw.

But it doesn't matter - if there is no class comment in there I would
still be left wondering if:

- It has been lost.
- The author was sloppy.
- If it is intentionally left blank.

So why not put a single line in there as it is btw in
LargeNegativeInteger?

> With methods it's even more frequently the case that a comment is a
> wasted distraction and an unnecessary maintenance burden.  We really
> don't need a lot of this kind of comment:
> 
> 	sillify: aString
> 		"sillify the argument"

I don't think anyone has argued that.

regards, Göran