Dino [SMTP:gte949e at prism.gatech.edu] said: 
[snipped & paraphrased to suit me :-)]

"...more comments, make 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."

~~~~~~~~~~~~~~~~~~~~~~~

Hear, hear.  Although I value code browsing as much as the next fellow (it
is, after all, essential to true understanding of the subject), I think
that, in general, the class comments should at least contain a brief
overview of how the author intended for the class to fit into the larger
picture (& I like the UML diagram idea somebody suggested too -- it would be
super cool if the browser could generate pictures to show how the classes
tie together).  It's OK if the comments are thin to start with; the author
of a class doesn't always know how his/her class will end up being used.
Besides, Ted K. just reminded us that these comments can be updated as
easily as the code and it really doesn't take any extra time to put a note
into the class comment when you update the public interface or add example
methods.

Actually, if we take the pains to put methods into well chosen categories,
we could obviate much newbie-related confusion.  E.g. put the public methods
into the "public" category!  Voila!  A self documenting interface!

I think it would also be nice if I could ask Squeak to print out a list of
all of the major subsystem classes.  It did take me some time to find out
what was there (and I have yet to really look at the kernel/debugger stuff).
Perhaps we could "register" subsystem "top level" classes by adding class
methods like isSubSystemTopLevel and subSystemName (sorry, these names are
just off the top of my head).  Then a viewer application could dynamically
grab the class comment for each top level class and generate some kind of
"report" of what is available in your image (perhaps one or two of you
gifted folks have already done this and I haven't found it yet? :-) ).  This
report generator might even go so far as to spit out protocol information
(kind of like the "Synopsis") tool does.

Anyway, I vote for the more comments, rather than less.  I promise that all
new code I submit will be commented.

Cheers!

---==> Chris

PS>  I believe that testing documentation is also useful for regression
testing.  When I worked on fixing some bugs in a feature I recently
submitted to Squeak Central, it was soon apparent that I hadn't done enough
testing on the first time through (my bugs had bugs :-) ).  So now I've
started adding a description of the tests I ran, on the code that I'm
submitting, to the change sets that I submit.  Since we don't have a formal
Quality Assurance organization, it might be useful if we could come up with
some forum, within the code itself, that describes tests that should be run
when changes are made to a subsystem.