Good, thorough Smalltalk reference

joshscholar at nightstudies.net joshscholar at nightstudies.net
Mon Jan 16 07:11:58 UTC 2006


Documentation, and it's lack is one of my pet peeves from my working life,
so forgive me my passion on this subject.  But perhaps I can say something
useful.

There are two kinds of code documentation that are useful:
1. Documentation that describe what a user of the system needs to know.
2. Documentation that describe what a maintainer / extender of the system
needs to know.
These can overlap, especially in the case of classes that are meant to be
subclassed - then users need to know about implementation details.

Users need to know the public interface (I'm thinking about the human end of
this, the API for a set of tools/class, including but not limited the formal
interface to any specific class). They need to know what each class is for.
How to use each class. What its limitations are.  And how the code fits into
the system, for instance what alternatives they have to using that
particular class.

Exactly the same questions need to be answered for each method.

If an object is a singleton, users need to know the name of the global that
holds it, and/or the method that accesses it. In Smalltalk a singleton
object can be hidden behind a chain of method invocation on a global. These
should be documented in one place so that a user knows all of his options
and can find everything.

Maintainers need to know all of the above plus:
    what dependencies (for instance default behaviors in Object) are,
    side effects,
    for each variable:
        what it holds (types),
        when it's initialized
        when it can change, what code can change it
     in general, life-times of data,
    hooks into the rest of the system,
    what other parts of the system uses this class,
    how to extend the class, add planned features
    if there are any surprises in how or where some data or function is used
anywhere in the whole system, that should be documented both in the source
and destination.
    For methods (and systems as a whole) what the algorithms are.

I'll grant that Smalltalk's tradition of having a word that names each
parameter in a method invocation improves the self-documenting quality of
Smalltalk code, but there are limitations to how much good that does.

I downloaded all of the books available and bought a copy of  purple book. I
don't think any of the books has reference documentation for each class, let
alone for each method or global.  I'll look into getting a copy of the
standard.

Anyway I think it's a good idea to put all that human communication in one
place, cross referenced etc.  You're right that any documentation will
become obsolete as soon as the code changes, but having documentation is
still worthwhile.  I suppose we could gat around that problem by making a
book auto-build from specially formatted code comments and encourage code
maintainers to keep their comments up to date.

Or maybe a having a documentation guru is a good idea.

Joshua Scholar
----- Original Message ----- 
From: "tim Rowledge" <tim at rowledge.org>
To: "The general-purpose Squeak developers list"
<squeak-dev at lists.squeakfoundation.org>
Sent: Sunday, January 15, 2006 9:51 PM
Subject: Re: Good, thorough Smalltalk reference


> > joshscholar at nightstudies.net wrote:
> >> Me too. I've yet to find a good reference for all of the standard
> >> classes.
> >> I don't need or want tutorials, I just want a thorough reference.
> It's not possible to have a 'thorough reference' other than the
> system itself. As soon as you add, delete or edit a method - which of
> course happens any time you load a package - it would be out of date
> and no longer thorough.
>
> A static bit of paper or pdf is essentially useless as soon as it is
> written when referring to a dynamic system. You can, certainly, have
> a fairly static description of the *language* Smalltalk since that
> doesn't change much. It would be short and not terribly helpful much
> of the time since you could memorize it in no time. A page or two at
> most, about as long as a list of C precedence rules.
>
> Almost any of the classic Smalltalk books on Stephan's site will have
> a decent level of reasonable-reference material but it will be
> incomplete for the Squeak system. Tough luck I'm afraid. Live with
> it. The only plausible reference is the system as it exists while you
> are examining it.  Any other way involves that quaint old-fashioned
> idiocy so beloved of the java-weenies, C++ chumps and other dinosaurs
> - sourcecode in files. I mean, what an idea. So last century.
>
> What we can have, should have and pretty much don't have is decent
> friggin' comments as to what classes are intended for, how they are
> implemented and their limitations, along with comments in the code to
> give some decent level of meaning. Comments in the system can be (but
> usually aren't) kept up to date. Better yet we could develop tools to
> replace the current browsers that make writing code more like writing
> documentation that has the implementation included as it goes, what
> my friend Dan Lanovaz refers to as a software book.  But then we'd
> get complaints from the sort of plonkers that claim 'oh, my code is
> so clearly written that it needs no comments'. Gits.
>
> tim
> --
> tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
> Strange OpCodes: JUM: Jeer at User's Mistake
>
>
>
>




More information about the Squeak-dev mailing list