Back to the issue... (was RE: Squeak coding style...)

goran.krampe at bluefish.se goran.krampe at bluefish.se
Thu Mar 4 09:00:53 UTC 2004


"Lex Spoon" <lex at cc.gatech.edu> wrote:
> 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.

Hehe, yes. But that argument is kinda silly IMHO. Because it would be an
argument for not writing any documentation at all. I mean, why take on
the hassle of maintaining it?

> 	2. They are an extra source of bugs.  Wrong comments are bad.

And again, only if they are indeed wrong. I mean, both these arguments
are only saying "Comments are bad because it will take time and effort
for me to keep them in shape". IMHO silly.

> 	3. They easily duplicate effort.  It is better to comment things in one
> place and where necessary to have links to that one place.

Definitely. And I have never said that class comments should be
duplicated. A reference is perfectly fine IMHO.

> 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.

So you mean that the information about LEAbstraction and LEApplication
is in the superclass?

Sure, I can sympathize with that way of doing it - I would still like
one line saying "See superclass." because then I can be certain that you
didn't forget to write it nor did it get lost somewhere (which has
happened).

> 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.

I agree with all this. As long as it doesn't turn into an excuse for not
writing suitable comments.

> 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.

I repeat the "Is it blank intentionally or did Lex just forget to write
it?"-argument.

> Do we really want, for example, every subclass of
> Morph to say "see the Morph superclass for more info" ?

Hopefully they have more to say than that. And if they don't then yes -
I would like a single line in there that someone wrote *intentionally*.
As a matter of fact, I don't care what it says - as long as it is there.

> IMHO, such a
> comment is just as wasted as this one:
> 
> 	x := x + 1.   "add 1 to x"	

This comment adds nothing to me as a reader because I am already looking
at the line in question and the code is obvious. But the same is not
true for a blank class comment for reasons I have already explained.

> 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.

And I agree with all this. Still want to reflect on it.

regards, Göran



More information about the Squeak-dev mailing list