I do agree with this....  but it would be nice if the code had some
comments too.  With more comments, it makes reading the code easier than
reading code with no comments.  Some parts of the code probably doesn't
need comments (like accessors and modifiers), but some of the code could
use a comment here and there just to let us know what is going on.

Also, it would be great if every class had an example class we could study
off of.  Sometimes an example class is worth a thousand words.

-- Dino


Ralph Johnson wrote:
> 
> My experience is that API-level documentation is not as important
> for Smalltalk as it is for other languages, because it is so easy
> to read the source.  The kinds of things that need to be documented
> in Smalltalk are the kinds of things that you can't get easily
> by reading the source, such as the big picture and how to do a
> particular task.  Part of the motivation of patterns is to be
> a way to describe the big picture a piece at the time, and also
> a way to describe how to do a particular task.  However, tasks
> might be better described by the class "cookbook".  The VisualWorks
> cookbook is a very good example of how to do this for Smalltalk.
> 
> A wiki is a very good way to capture documentation like this.
> It is nice for both patterns and cookbooks to point at examples
> in the code.  So, the swiki might eventually be enhanced to
> point into the codebase.  But in the meantime, people can just
> add things as they realize they are important.  A good way to
> start is just to answer questions as they are asked, and then
> to organize the answers.  There seem to be a lot of questions
> about Morphic, so that might be a good place to start.
> 
> -Ralph Johnson