I'm not trying to say you're a fool.  It is great that this
method works for you.  But do you want smalltalk to
be for people who tinker or do you want a larger user
base?  Larger user base buys you more bodies to write
code so things get done faster, new killer apps get made.
It also buys you more testers and potential bug fixers.

I just don't find "code is the documentation" acceptable at
a professional level.  Open software tried to say that in the
beginning and they were shot down (any that wanted
to make money anyway).  If you want to play around,
take your watch apart to see how it tells time, ok.
But if my company has millions of dollars riding on your
software there had better be some documentation.

Do really think it would be ok to deliver a product to a
customer and say "well, the code is all there, dig around
and you should be able to figure out how it works in no
time"?

>From: "Ramon Leon" <ramon.leon at allresnet.com>
>Reply-To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>To: "'The general-purpose Squeak developers 
>list'"<squeak-dev at lists.squeakfoundation.org>
>Subject: RE: Thoughts from an outsider
>Date: Wed, 30 Aug 2006 11:35:42 -0700
>
> > The fact is, no matter how obvious the language is there are
> > patterns we use.  Sure in some instanses the method can be
> > obvious enough to be understood.  But there are plenty of OO
> > patterns that are not obvious if you have not seen them
> > before and sometimes even if you have.  You may be able to
> > read from the code what it is doing, but you are going to be
> > thinking "why in the world is he doing this?".
> >
> > Also, if you work with a pretty complicated subsystem (i.e.
> > uses lots of underlying objects to get work done) do you
> > really find it a good solution to dig through class after
> > class after class just to find out what an interface (i.e.
> > what the subsystem end users use) method does?  And even if
> > you do, someone new to the language isn't.
>
>This is the difference between using a framework and using an API,
>Smalltalkers like frameworks, which by their very nature, require you to
>understand how they work.  You make it sound like digging through classes 
>is
>hard, it's just a couple keystrokes, browse here, browse, there, check out 
>a
>few examples, bam, ok, makes sense now.  I not only find digging through
>classes a good solution, I find it's the only one I've ever found that
>works.  Documents lie, code doesn't.  I consider understanding how 
>something
>works, a prerequisite to using it well.  And frankly, I can bounce around
>the code, in a far more organized and faster manner than I could through
>some document.
>
> > And must every usage of a new subsystem be a trip through
> > every method in that system?  Can't I just get a list of what
> > the useful methods are and how to use them?
>
>If you have a task to perform, you should be able to just browser class
>names to see who might do that, it's a simple task to quickly check a class
>for it's responsibilities.  Well designed frameworks make this a breeze.  
>As
>I said earlier, getting a list of the useful methods and how to use them, 
>is
>only a hotkey or two away.
>
> > I appreciate the simplicity of the language, but it is
> > because of this reason one must guard against the false
> > feeling of "self documenting code".  You don't have to
> > document every method ever, but ANY interface to the
> > subsystem should be documented some how and any method over a
> > certain number of lines should be documented.
> >
> > Even if you coded right in pure English, I still wouldn't
> > know *why* you did it the way you did, and therefore I
> > wouldn't know *why* I shouldn't just change it.
> >
>
>Self documenting code is not a false feeling, it's a point of view.
>Smalltalkers in general don't write long methods, so that's not an issue.  
>I
>find class and method comments, totally sufficient for me to grok how a
>system works, a quick look at the hierarchy browser, couple of samples of
>those classes in use, and away I go.  I usually find when something is done
>weird, there is a comment explaining why it was done that way right there 
>in
>the code, as it should be.
>
>I appreciate that some people want more documentation, that's a valid point
>of view, but let's not insist that those of us who think the many browsers,
>classes, categories, method categories, and class and method comments are
>sufficient documentation are somehow foolish, we're not.  Some people need
>instructions on how to assemble things, others just look at the parts,
>tinker a bit, and figure it out, Smalltalk is wonderful for those in the
>latter camp.  I'll take being able to look directly at the class over
>looking at a document any day of the week, it's the best documentation 
>there
>is as far as I'm concerned.
>
>