--- Lex Spoon <lex at cc.gatech.edu> wrote:
> "Göran" Hultgren <gohu at rocketmail.com> wrote: 
> > 2. Class comments. Class comments. Class comments. I use to say that.. Whatever you do, AT
> LEAST
> > write a descent class comment. Unfortunately a lot of the base classes are uncommented. And of
> > course, somebody else than the author could write them. But it still would be best if the
> authors
> > wrote them themselves. Yes, this is criticism! :-) :-) And the idea to change the browsers so
> that
> > the comments are visible without a "mode switch" could also make missing class comments more
> > visible and annoying, thus fostering the culture of making sure they are there.
> 
> Okay, everyone says this, but is it true?  Okay, here goes a start at
> it.
[SNIP - proof of exactly how many missing class comments there are]

I agree that there are indeed a lot of good comments, and I also agree that there are a lot of
classes that do not really need a lengthty comment, perhaps not even a comment at all.

But I have nevertheless stumbled upon base classes in my explorations in Squeak that are
uncommented and since they are indeed highlevel base classes, IMHO I think that they should be
commented - no matter how few they are. :-)

BUT... this is no "hard criticism", just a detail that would enhance the experience for a newbie.
I myself do not really get disencouraged by it, on the opposite - it starts itching in my keyboard
fingers...

> But enough doom and gloom.  On the good side, most of the comments that
> are there, really are quite good.  Someone could learn a great deal
> about Squeak by just reading through  class comments, even with as many
> missing as this.

Agree.
 
> Furthermore, while 500+ classes might seem daunting, note that only 22
> of these are in the core Kernel-* and Collections-* categories.  Some
> dedicated Squeak ought to be able to knock these out in no time.
 
And of course, the Open Source way of doing it is to write the comment yourself (myself) and
submit it to the list, or whatever so that someone could bless it.

regards, Göran

PS. I might actually do this for some of the classes... DS

=====
Göran Hultgren, goran.hultgren at bluefish.se
icq#:6136722, GSM: +46 709 472152, http://www.bluefish.se
"First they ignore you. Then they laugh at you.
Then they fight you. Then you win." -- Gandhi
__________________________________________________
Do You Yahoo!?
Talk to your friends online with Yahoo! Messenger.
http://im.yahoo.com