A modest proposal... DOCUMENT!

Charles-A. Rovira crovira at wt.net
Thu Feb 17 21:44:15 UTC 2000


I defintely agree with Lars.

The lack of documentation as to the intent of a class (why is this thing even in here,) the structure of its variables (global, pool, class, instance, method and block vars and the classes the var can take would halp a lot, (a parameter called "aCollection" doesn't tell me much about what its a collection _of_ and that may be important,)) the protocols (why is this distinction even in here,) and functionality (why is this method even in here,) along with some EXAMPLES are the biggest hurdles to overcome.

Use comments and people wont be so mystified. From experience with other Smalltalks and from my reading of Squeak!, Squeak! is a winner _if_ you can ever figure it out and have that much time to waste ramping up and finding what objects are for what purpose and which can be safely ignored.

There are a very few things I'd like to see changed. ENVY/Developper and by extension IBM Smalltalk have a class hierarchy that's better factored out than Squeak.

You should really reconsider your code if you ever find yourself writing stuff like:
SortedCollection>>at: anInteger put: anObject
 "Storing into a SortedCollection with at:put: is not allowed."
 self error: 'to add to a sorted collection, you must use add:'

The error is the class writers' not the class users'. Refactor, add an abstract class if you need to and be ruthless in the application of the six reason to subclass...

The hierarchy should only accrete as you descend. Subclass when and only you need to _add_:
1) structure (class and inst vars, use of pools & globals)
2) functionality (methods added and/or overloaded, never just negated!)
3) identity (isA<classname> ^true & add Object>>isA<classname> ^false)
4) aggregate complex parameters into tuples ("a la" VisualAge for Smalltalk)
5) aggregate complex returned values into tuples ("a la" VisualAge for Smalltalk)
6) participation in relationships (Nobody ever gets this one! It requires expanding the entire concept of associations into a schema controlled object instantiation and connection, disconnection from relationships, and eradication of associated subordinate instances depending on what the schema requires/allows. All persistent objects participate in relationships rather than contain other objects. The implementation of the storage may differ but the end is the same, using foreign keys into an RDBMS, ObjectIDs into a CODASYL network database or object hashes onto an OODBMS)

Dan Ingalls wrote:

> Folks -
>
> Lars Nilsson <lars at cymfony.com> just sent me an interesting message basically saying that, as a professional programmer, he didn't find the syntax to be that much of a problem, but that the scale of the class library and the paucity of documentation and examples were more of a barrier.
>
> I don't want to get (back) into either of these topics here, but it reminded me of another related project on my personal list (it has fallen off the official list) that might interest some of you, and on which I would welcome suggestions or contributions (see the note at end).
>
> Analogous to the task of giving a newbie competence in basic Squeak is the question of how to turn a competent Squeak programmer into a "real hacker".  I once started on an "archaeologists guide to the Squeak image" (I think this actually made it out onto one of the wikis) as a written approach.  It would probably be a help at least to finish this, but some of our conversations about help for the novice make me think there may be a better approach.  Also I have to credit Alan's continued insistence that (to paraphrase slightly) "If we do it right, it should help the swat teams as well as the newbies."
>
> What separates a Squeak hacker from a normal Squeaker is, I believe, the same kind of thing that separates a competent Squeaker from a newbie.  In each case, the expert sees what can't be seen, while the novice, of course, does not.
>
> A competent Squeaker "sees" a whole active structure behind any piece of static or dynamic code -- the structure of the objects including inherited state, the message interface of objects, including inherited methods, temporary variable bindings, the stack structure, and so on.
>
> What do we do for the novices?  Do we show them a picture?  No.  We give them at least three different views (browsers, inspectors, debuggers) in a non-pictorial framework, and with no attempt to build or maintain any coherence of the picture that they need to understand.
>
> I have learned from giving demos that one of Squeak's most convenient features -- the ability to execute text anywhere on the screen -- can be incredibly confusing to newcomers.  The ability to print the value of an expression in the debugger is generally understood and helpful (except that it dirties the text).  But typing something in the middle of a browser pane as an example may seem like utter nonsense if the viewer is just learning that this code pane is a view of a method;  what on earth is the relationship to the new thread that is spawned out of the text editor from the middle of this method that he was just beginning to understand?
>
> It would probably be much simpler if do-it and print-it copied their selections to a transcript, and if the results then appeared below.  Or at least if there were a pop-up pane for printed results that would not dirty the text in which you evaluate an expression.
>
> The question is:  What are the pictures we use to think with, and how can we build them and reinforce them (and not undermine them) for newbies?
>
> And how about the swat teams?  An interesting topic that has arisen several times on this list is, "OK, I have SqueakV2.sources (or some more current listing of all the classes and methods);  is there a way I can just compile it and run Squeak?"  This is what got me started on the archeologist's guide.  Here again, there is a picture that the Jedi's have in their mind.  They see the process scheduler, the display structure, the event handler.  They see the Smalltalk dictionary and the shared pools, the changeSets and the project tree, the textStyles and text with runcodes for emphasis, changes files chunks and remoteStrings.  And Undeclared, the dependents dictionary, and obsoleteClasses.  And on, and on.
>
> What do we do to build and maintain a coherent picture of all this structure that is the Squeak image?  Almost nothing.  What could we do?  That's the question.
>
>         - Dan
>
> [Suggestion:  This is another potentially open-ended topic like syntax (the last in this series of "since you asked what we're up to").  Perhaps it will help if, in our discussion, we try to limit ourselves to practical items like "the xxx system <url> does a good job of this" or "try the attached fileIn for a concrete view of the yyy hidden structure in Squeak."]





More information about the Squeak-dev mailing list