On Sun, Jan 20, 2002 at 02:17:41PM -0800, Les Tyrrell wrote:
> 
> Keeping documentation consistent with an evolving code base is a bit hard.  In
> Squeak, class comments don't get very much attention, probably as much due to
> the way the browsers operate as anything else.  In order to see a class
> comment, you have to do a small bit of extra work, whereas to see code all you
> have to do is make a few mouse clicks that are probably nearly instinctive to
> the Squeak programmer anyway.  If the browsers were configured to show the
> class comment whenever reasonably possible ( for instance, perhaps any time
> that a class is selected but a method is not ) then maybe they would get more
> attention.  As an example, I've attached some methods for Browser that I just
> wrote for Squeak 2.2 that do something like this.

<gripe>
Nonsense, the tools are not the problem. Posting classes with no class
comment and methods listed in the 'as yet unclassified' category is just
plain sloppy. It takes 10 minutes to write a comment and put methods into
meaningful categories, and it takes your readers many times that long
to figure out how things work if you don't bother.
</gripe>