A big teacher wish

Richard A. O'Keefe ok at cs.otago.ac.nz
Thu Nov 28 02:05:21 UTC 2002


Roel Wuyts <roel.wuyts at iam.unibe.ch> wrote:
	I like the idea, but not these names, they are way to generic. 

Exactly so.
	Especially the 'knows' is really too much, and it is also a form of 
	sharing (it just has a different scope). So maybe something like this?
	
	>> Morph
	>>     subclass: #MyMorph
	>>     has: ' myTarget lastTime '
	>>     instancesShare: ' CloseBoxImage '
	>>     poolsShare: ' Colors '
	>>     category: 'Morphic-Samples'!
	
For me, 'has' is a relation between objects (THIS ordered collection
_has_ THIS array as one of its parts) or a relation between classes
(AN INSTANCE OF OrderedCollection _has_ AN INSTANCE OF Array).
	
'has' is not just "way too generic", it suggests the wrong thing.

The most salient thing about #myTarget and #lastTime is that they
are VARIABLE NAMES.  What on earth is wrong with using the word
'variable' here?

The next most salient thing about these things is what their LIFETIME
is.  Their lifetime is the lifetime of an instance.  So the most
intention revealing name here is something that says
'variable with lifetime of instance', possibly in fewer words.
I know, we could say 'instanceVariables:' and that would convey
the meaning concisely and accurately.  It doesn't matter if it's
a bit long because nobody ever types it.

Now let's look at 'instancesShare'.  Let's find an example of instances
sharing something.

    x := 'boojum' copy.
    y := Array with: x.
    z := Array with: x.

Now we have two instances (y, z) of Array sharing something.
What they share is a String.

Object sharing is FAR too important a concept in OO to abuse the
word to refer to the scope of variable names.

What's the most important thing about 'CloseBoxImage' here?
The fact that it names a variable.
What's the second most important thing about it?
The fact that it has the same lifetime as the class.
A good intention-revealing name would be something along the lines of
'variable with lifetime of class', possibly in fewer words.
I know, we could use 'classVariables:' and that would convey
the meaning concisely and accurately.  It doesn't matter if it's
a bit long because nobody ever types it.

Now let's look at 'poolsShare'.  Well, it's just plain WRONG.
'Colors' is not the name of something that some pools share',
it is the name of a pool.  It would have to be 'poolsShared'.
However, what's a pool?  Especially for beginners, you need
a bit of help here.  A pool is a Dictionary, so we need a
name something along the lines of
'dictionary of infinite extent variables whose scope may be
shared with other not hierarchically related classes'.
Since the things named aren't variables but dictionaries,
we want something that says "xxxDictionaries:".  Anyone who
knows/remembers Fortran would appreciate my preference,
'commonDictionaries:'.  "Pool" is the least obvious part of
the name, so why retain the one bit that _isn't_ very helpful
and jettison the part that _is_ helpful?

'instanceVariables:' and 'classVariables:' are well-nigh perfect
intention-revealing names, once you grasp that the important distinction
is not whether they are "shared" or not (ALL Smalltalk variables can be
"shared" in _some_ sense) but what their lifetime is.

Remember that NOBODY types these names in by hand.
Smalltalk makes the template for you, and you just fill in the
different bits.

Instead of messing about with the names (and thereby greatly diminishing
the utility of those wonderful free Smalltalk books), if anyone is
seriously bothered about whether beginners understand these words or
not, they could do something REALLY practical and potentially useful:

    MAKE
	Class class>>templateForSubclassOf:category:
    GENERATE A TEMPLATE THAT CONTAINS HELPFUL COMMENTS.

So instead of seeing

    Object subclass: #NameOfSubclass"
	instanceVariableNames: ''
	classVariableNames: ;;
	poolDictionaries: ''
	category: 'Collections-Text'

a beginner would see

    "Edit this template to create a new class."

    Object subclass: #NameOfSubclass"
	instanceVariableNames: ''
	classVariableNames: ;;
	poolDictionaries: ''
	category: 'Collections-Text'

    "Change Object to the name of the existing parent class.
     Change NameOfSubclass to the name you want the new child class
     to have.  Do not remove the # sign, it is important.
     Instance variables are variables that live inside objects;
     when an instance is made, the variable comes into existence;
     when an instance disappears, the variable disappears.
     To declare such variables, put their names, separated by spaces,
     inside the string after instanceVariableNames:.
     Class variables are variables associated with classes rather
     than instances; when a class is created or loaded, they come
     into existence, when the class is destroyed they go out of
     existence, and they keep their values no matter how many
     instances there are.
     To declare class variables, put their names, separated by
     spaces, inside the string after classVariableNames:.
     Pool dictionaries are an advanced feature you don't need to use,
     so leave that line untouched."

I'm not picky about the wording.  It should certainly be localised.
Basically, there is NO perfect set of words you can use here which
will be instantly obvious to all people.  ESPECIALLY if you change
the words so that they can't use any existing book!  Generating some
kind of helpful comment, even if it's just
    "Click on this link for a tutorial about creating classes."
has got to be FAR more helpful.



More information about the Squeak-dev mailing list