Learning Squeak

Les Tyrrell tyrrell at canis.uiuc.edu
Sun Jan 20 22:55:24 UTC 2002


----- Original Message -----
From: David T. Lewis <lewis at mail.msen.com>
To: <squeak-dev at lists.squeakfoundation.org>
Sent: Sunday, January 20, 2002 2:40 PM
Subject: Re: Learning Squeak


> 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

> <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>

BAH!  I believe the tools can definitely have an impact.

The normal mode of interaction with the tools is to look for code.  In that
mode, class comments are not shown by default.  Thus, their existence or lack
thereof is not as visible to the user as the methods or even the class
definitions.

Just off the top of your head, without looking, do you have a feel for what
percentage of classes are actually commented?  How does that compare to the
actual percentage?  Do you have a good feel for which of the comments are
actually accurate and consistent with the current implementation?

I'd wager that you would have a better feel for both of these figures if the
class comments were presented to you at least as often as the class
definition, and that is what those methods I posted do.  This is a very
testable notion.

An even stronger reinforcement would be to indicate in the class list of the
browser which classes are commented and which are not.

- les





More information about the Squeak-dev mailing list