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

First, 517 classes out of 2443 in my image have no comment.  That's 
21%, which indeed sounds like quite a large percentage.

But how many of these are core classes??  Perhaps the core is documented
just fine, and its classes on the fringe that have this trouble?

Well, in Kernel-*, all classes have comments except the following:

	ProtoObject
	MorphicObjectOut
	ClassBuilder
	ClassCommentReader
	TranslatedMethod
	Delay
	MethodHolder
	ValueHolder
	Workspace


Out of fifty-something classes in Kernel-*, again around 20% are
uncommented.

Okay, how about Collections-*?  Missing comments in:

	IdentityDictionary
	IdentitySet
	Set
	TextAction
	TextDoIt
	TextLink
	TextURL
	Array2D
	WordArrayForSegment
	LimittedWriteStream
	MimeConverter
	TextStream
	

Out of ~65 classes, this is yet again right around 20%.  Squeakers sure
are consistent about one thing when it comes to their comments.

Okay, what the heck, I'm on a roll.  Here are percentages for some other
major areas:

	Morphic  145/264  (54%)
	Network  49/164 (30%)
	Tools 20/54 (37%)
	System 14/84 (17%)


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.

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.


Lex