[Squeakfoundation]re: TrueType font support and 3.6

[Colin Putney]

On Tuesday, June 24, 2003, at 05:33  PM, Andreas Raab wrote:

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

I'll agree with you that comments can give you more information about 
the author's intention. But the examples you gave don't give me anymore 
information than the code. From the code, I already know that the 
author was thinking type, not property. Otherwise, he would have called 
the method #isSymbolic. Now, if the author wants to tell me more than 
that, ok:

Object>>isSymbol
	^ false

	"This method really does need to be here, and not in String, 
because..."

>> 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? ;-)

No, but I would say that comments do get out of synch with the code 
quite easily. Expecting people to chase down all the comments that are 
affected by their code is probably not reasonable. That's not, of 
course, an excuse for writing obscure code. By putting an much of my 
intention as possible into my choice of selector, I can make my 
intention clear not only to readers of my method source, but also to 
readers of methods that send that message.

I do concede that a selector is a lower-bandwidth communication channel 
than a comment. But by limiting myself a bit in that regard, I gain 
quite a bit in terms of audience. This is also mitigated by the 
Smalltalk IDE. If my audience doesn't quite grasp the subtleties 
Object>>isSymbol returning false, with one click they can look at all 
the other possible responses to the question "are you a symbol?"

I suppose ultimately, this is just a question of style. If you put time 
and effort into writing thoughtful comments in your code, and put it 
into refactoring my code for clarity, we both win. I can understand 
your code and you can understand mine.

The problem is that "clear and easy to understand" is a difficult 
standard for the Guides to apply. But I urge them not to settle for the 
easier standard of "has comments." Sure, the review process needs some 
improvement in order to speed up harvesting. But right now it does 
encourage contributors to make their code as readable as possible. 
After all, if the reviewers can't understand your code, they're not 
likely to approve it.

Colin