Hi Yoshiki and all!

Yoshiki Ohshima <Yoshiki.Ohshima at acm.org> wrote:
>   Göran,
> 
> > I mean, sure, some of these can have short comments - but is it just me
> > getting ANNOYED when there is NO COMMENT AT ALL?!
> 
>   I am, too (regarding clas comments, but not method comments for most
> of the case).  What should I do?

First of all - let me reiterate that I am very, very impressed with your
work. I REALLY wasn't trying to criticize you in this, but I agree it
might have sounded like it. I deeply and honestly apologize for that.
Really.

I was however voicing my frustration over harvesting being done of new
classes without class comments - I thought we had agreed on that new
classes should be checked for that. And perhaps it was just an honest
mistake, but harvesting should IMHO include such basic steps as to check
for class comments. I really do think that.

So optimally someone should have told you that, hey - you have forgotten
the class comments! And then you would have added them. End of story.

Now, hoping I haven't offended you, nor anyone else *including* the
harvesters, this is what I think we should do:

You simply write a class comment for each new class that have been
introduced into the image.

Note that I don't think we need to be formal about the format or the
content or the length of the comments - I don't care! :) Short comments
are perfectly fine - they can even be ONELINERS if that is deemed
enough.

I also don't think you need to follow any special format and I
definitely wouldn't want to force people to describe instvars etc unless
they want to themselves because it may help understanding the object.

Also - note that the *existence* of a very short class comment also
tells the reader something: That this class is so trivial or simple or
obvious that *there is no need* for a longer description.

If the class comment is *missing* then the reader doesn't know this.
 
> -- Yoshiki

regards, Göran