[Squeakfoundation]re: TrueType font support and 3.6

[Andreas Raab]

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

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"

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.

Cheers,
  - Andreas