On Mon, 1 Feb 1999, Dan Ingalls wrote:

> The lines of code thing is just plain confusing.  Generally less is
> better, and I just don't think you cn compare systems this way.  
> Consider...
> 
> 	| strm |
> 	strm := WriteStream new on: (String new: 10).
> 	tempNames do: [:n | strm nextPutAll: n; space].
> 	tempStr := strm contents.
> versus...
> 	tempStr := String streamContents:
> 	    [:strm | tempNames do: [:n | strm nextPutAll: n; space]].
> 
> The streamContents: form encapsulates a variable declaration, a stream
> creation, and the extraction of a stream's contents.  Every time it
> gets used reduces opportunities for errors in those places.  And you
> can be pretty sure that streamContents: is correct, because it has
> been in use every millisecond for the last three years that the
> current Squeak image has been running (think about it ;-).

Your choice of example was particularly interesting to me.  As I am still
new to Squeak and Smalltalk, even though I consider myself an experienced
programmer (and a very good C++ and Java coder), I'm occasionally
frustrated by the learning curve to write code that feels like Squeak,
mostly because I'm not familiar with what the class libraries can do. The
only solution is simply to get more practice writing code, and that's what
I've been trying to do.

For example, performance is important to me, and one of my long-term goals
is to be able to help in some way with the Jitter project, so I've been
reading the Dragon book and converting the examples to Squeak.  For the
first example (an infix-to-postfix translator), I ended up writing some
code exactly like your first example.  I strongly suspected that there was
a better way to do it (it just didn't feel right), but it was amusing to
see you answer my question before I had a chance to ask it!

What does this mean for Squeak, particularly in terms of making it
accessible to programmers, like myself, who already know C++ or Java, but
aren't familiar with Smalltalk?  I suspect that as Squeak gains in
popularity, more of these programmers will come in and start writing C++
or Java-looking Squeak code, and anything which can be done to improve the
situation is a good thing.  The ability to easily browse any source code
in the system is a real plus, simply because exposure to high-quality code
in any language is a great way for the coding style to rub off on
newcomers.

However, what I really miss is the equivalent of books like "Java in a
Nutshell", which features a highly lucid quick reference to all Java
classes, and tips on how they are intended to be used.  While Java already
came with javadoc descriptions of each class, it was often difficult for
me to see exactly where to begin, and it's all too easy to skip over a
method which may be exactly what you need.  Referring back to my Squeak
experience, even though I had full access to browse the messages for
String and WriteStream, I just didn't see the streamContents: message.

Anyway, since you had mentioned better documentation as a goal for future
Squeak releases, I hope these comments give you some idea of the sort of
documentation I (and presumably many others like me) would find very
useful.  It doesn't have to be a printed book:  in my case, simply having
a brief summary of commonly used messages (ideally with example code
snippets like the one you gave) summarized in the help text for each
system class (so I can hit the ? button and read how to use it) would be a
BIG improvement.

-Jake