[Squeakfoundation]re: TrueType font support and 3.6

[Andreas Raab]

Colin,

> > In one of the methods we ask for a type in the other one we 
> > ask for a property. From the code it is totally unclear what
> > we mean (there could be a class Transparent) and it is
> > *exclusively* the comment which tells us that
> > we're asking for a property vs. a type.
> 
> I don't think that's a terribly meaningful distinction. All you can 
> really say from seeing this method is that objects are 
> neither symbols nor transparent by default.

That's what you can say from the code. From the comment you may find out how
the author *thought* about it. You are slightly missing my main point which
is: Comments not only explain what happens they also explain how the author
thought about this to begin with. This is often quite subtle information
(e.g., using "a Symbol" tells us that the author thought about this as being
a member of a set of first-class objects) which can be helpful in
understanding fundamental invariants.

> And the reverse is true, too. Isn't membership in a class a property? 
> If I create a class that looks like a Symbol and quacks like 
> a symbol, but isn't actually a subclass of Symbol, it makes the
> comment in Object>>isSymbol wrong.

No, it's not. The meaning of #isSymbol as defined by the original author has
been changed by _you_ generalizing it into something which was not what he
anticipated (or else he would have written the comment differently, perhaps
"answer whether I am a unique string"). 

So it's not that the comment is wrong - it's that you changed the meaning of
the message and therefore you should change the comment appropriately. Or
would you say that we shouldn't comment classes and (in particular) instance
variables because you can store anything in them and doing it would mean
that the class comment is wrong? ;-)


> > Morph>>bounds: newBounds
> > 	"Set my bounds to newBounds"
> 
> The comment does indeed tell us that. But so does this:
> 
> Morph>>bounds: newBounds
> 	bounds := newBounds

See above. If you write comments you put a lot of your way of thinking about
the problem into it. For example, I recently found myself writing comments
like "Indicate that X should happen" for accessors. If I find comments like
this in my own code it reminds of a lot of things that are not being said
elsewhere.

> Sure. I'm not claiming that comments are never useful. Just that 
> they're not universally useful.

If you write them deliberately (e.g., not just "because you have to") I
think they are universally useful. I'd say that every method can have a
useful comment of sorts, that you can write comments in a way so they
contribute something in addition to the code.

> Consider which you would rather have: rare but meaningful comments, 
> written because the author wanted to clarify something, or common but 
> trivial comments, written because the author wanted his work accepted.

If I have the choice? Lots of meaningful comments, of course! ;-) But that
wasn't your original question (to which I responded) about whether #isSymbol
_can_ have a useful comment.

I'm not trying to kid myself about enforcing comments for everything (I'm
not _that_ big of a fool ;-) in particular because enforcing them would lead
to exactly the kinds of trivial comments you mention. Yet, I still think
that "public" methods should be commented.

Ha! I just had an idea (not sure it's feasable but what the hell): How about
auto-classifying methods with no comments as "private"? APIs ought to be
documented, shouldn't they? ;-)

Cheers,
  - Andreas