On Tue, 19 Oct 2004 19:15:54 -0400 , lex at cc.gatech.edu said:
> goran.krampe at bluefish.se wrote:
> 
> > And also - what you are proposing (?) is AFAICT what we have been doing
> > over the years. And it hasn't really worked, has it? I have just
> > collected some stats (code below and printout) on 3.5, 3.6, 3.7 and
> > current 3.8. If you look at percentage of classes without comments it
> > was about 43%->40%->37% (positive trend? hard to say, depends) and now
> > 42% (oops). Of course, 3.5 to 3.6 removed a LOT of classes so more
> > analysis is needed to get the whole picture.
> 
> Have you tried counting the *number* of *commented* classes?  That has
> surely increased over the years.

Well, depends on what you're counting.  Probably the number of commented
classes in the Full distribution?  (I think Goran was counting Basic. 
Full is probably more appropriate.)  I agree that we want to increase
the total volume of quality Squeak code, but by this I would mean all
Squeak apps (such as Seaside, etc.) some of which may not be included in
Full.  In other words, we want to increase the size of the community
creating quality Squeak code, too.  The more the better, basically.

But I'm not sure if that applies to the Full distribution... it would
probably be good to add more stuff to Full, but not at a limitless rate.

Anyway, I see what you're saying... the total number of commented
classes has not likely gone down, because that would mean that people
are either removing comments from exiting classes, or replacing old
commented classes with new uncommented ones, which is probably
relatively rare.

> I really don't care that the
> percentage has gone down.  Truly.  So what if it has?

I still think it's generally bad if the percentage has gone down.  The
burden of writing comments at the class level (as opposed to method
level) just isn't that great, compared to the benefits, even if Squeak
is still evolving and a bit crufty.

> > > If we reject code then we spoil the open source process we have going
> > > and make it hard for people to fix (comment) the code.  But of course,
> > > putting in uncommented code reduces the *percentage* of commented code,
> > > perhaps indefinitely.
> > 
> > Note that having a rule saying that all classes should have a comment
> > (no matter how small) is IMHO not a rule that will reject code. I
> > honestly believe that the author would take the little time needed and
> > just fix it.-
> 
> Well what is it then?  If it's just a statement of what we would like,
> then I am pretty well agreeing with you.  It's the rule part that
> bothers me.  We have enough barriers and enough load on the harvesting
> process already.

I don't think the rate of harvesting would be significantly slowed by
requiring class comments.  IMHO the slowness of harvesting has had more
to do with how many people have had access to the update stream and
other issues.

Anyway, I've been thinking we should add something to the update
broadcasting mechanism so that it checks for the existence of class
comments and a few other basic things such as a changeset preamble,
method initials/timestamps, and no linefeeds.  (Actually I think it
already checks for linefeeds.)  So then I guess class comments would
become a hard "rule". :)

The update broadcasting mechanism should make it as easy as possible to
fix these on the spot, by direct prompting.  Fixing linefeeds is easy. 
Adding method initials should be doable... the person broadcasting
should know who the author is and be able to enter the missing initials.
 The broadcaster should also know enough about the basic intent of the
changeset to enter a short preamble on the spot if forced to.

With class comments, the broadcaster could be prompted to fill in a
missing comment.  Of course, this is a problem if the broadcaster is not
the author, although now that we're adding update-access for more
people, quite often the broadcaster will be the author.  But if not,
hrmmmm, the broadcaster could either:  1. Go tell the author to add
comments  2. Fill in the comment with something like "Comment to be
added soon by John Doe and Janie Jones (the authors)".  (There could be
a prompt to fill in all empty class comments with this phrase, in
extreme cases like 80 missing class comments with m17n.)

Anyway, I want to add this stuff soon to the broadcasting mechanism. 
Maybe I'll leave the class comment enforcement out at first.

Ideally, these checks could also happen further "upstream"... there
could be a simple changeset verifier utility that does these checks that
anyone could use.  Anyone posting an [enh]/[fix] with intent to be
included in Full would be encouraged to make sure it passed the verifier
first.

Of course the verifier should only do the really must-have checks.  In
theory it could get into doing SLint checks and that sort of thing, but
then that might actually slow the process down a bit too much. :)

- Doug