[Squeakfoundation]re: TrueType font support and 3.6

[Colin Putney]

On Tuesday, June 24, 2003, at 03:31  PM, Andreas Raab wrote:

>> Take the pathological case of the recent #isSymbol fix. Do you really
>> think that
>>
>> isSymbol
>> 	^ true
>>
>> would be made easier to understand by adding a comment?
>
> Absolutely. Here's why:
>
> Object>>isSymbol
> 	^false
> Object>>isTransparent
> 	^false
>
>
>> What would it say?
>
> Object>>isSymbol
> 	"Answer whether I am a Symbol"
> 	^false
>
> Object>>isTransparent
> 	"Answer whether I am transparent"
> 	^false
>
> 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.

Take the case of #isTransparent. Because "transparent" is an adjective, 
I know that this is a property of some kind. But that property might be 
implemented by a class. The only way to know what transparency *means* 
is to look at the cases where #isTransparent might return true.  There 
could be a Transparent class that always returns true. (But it would be 
an oddly named class, don't you think? Objects should have noun 
names!). There could also be various classes of colour that might 
return true depending on their alpha values. There might be a kind of 
InvisibleColor floating around that always returns true.

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.

> Personally, I'm not quite sure about whether to *require* comments for 
> all
> methods but I think that all "public" methods should have a comment. In
> _particular_ accessors - if I look at one of those where it's not
> immediately clear what the variable means the comment can help to 
> achieve
> better understand of what exactly this method means. It also helps
> explaining intent, e.g., whether we expect to change some variable or
> whether we expect a service. For example:
>
> Morph>>bounds: newBounds
> 	"Set my bounds to newBounds"
>

The comment does indeed tell us that. But so does this:

Morph>>bounds: newBounds
	bounds := newBounds


> Morph>>bounds: newBounds
> 	"Change my bounds to fit the new bounds"
>
> tells us that we are expecting a service and therefore assumptions 
> about
> identity may be totally off. E.g., if I read the first comment I'd 
> assume
> that the following holds:
>
> 	aMorph bounds: box.
> 	self assert:[aMorph bounds == box].
>
> In the second I wouldn't. So yes, even if it's restating something it 
> can
> still be VERY revealing to have a comment.

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

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.

Colin