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
|