Hi all!

"Andreas Raab" <andreas.raab at gmx.de> wrote:
> >> Maybe if you would calm down a little on the subject (I really don't see 
> >> why
> >> this particular issue makes you so touchy)
> >
> > Interesting question. Let me think... I guess it has to do with our
> > ambitions coupled with our seemingly inability to even do the smallest
> > things right. :) Like, how are we *ever* going to turn Squeak into the
> > exquisite artifact we all want it to become, if we can't even bother to
> > tell other people what our objects are?
> >
> > We all know that "later" in "I will write that *later*" never comes. It
> > is the same for unit tests.
> 
> Sure, it may seem so. But on the other hand, we are an incremental community 
> and as it turns out, not overly interested in writing class comments (I mean 
> if even you agree that you don't always do it ;-) So the point here is to 
> say "let's deal with reality" instead of wishing for something that isn't 
> gonna happen any time soon ;^)

Eh... well - I disagree. :) If we don't strive for increasing quality -
sure, forget about it all.

But if we DO, then I can't see your point. I mean, I assume you aren't
simply saying that we shouldn't care about the quality of the code
entering the image? Probably not. And if we *should* care, then it will
boil down to having either rules, or mechanisms nudging us in the right
direction. Bah, whatever... can't believe that I am arguing about this.

> >> and just start treat these things
> >> as bugs (as in: PluggableMumbleMorph cannot have a border width > 2) it
> >> would be a little easier?
> >
> > Well, only if there is a common agreement that this IS a bug. Otherwise
> > they will not get fixed anyway.
> 
> I think most people will agree with that POV. It's one of these things where 
> the term "should" becomes immensely important as in "this method SHOULD 
> check for boundary conditions" or "this class SHOULD have a comment".

Oh? Ok. Can't see how this is so obvious given your previous reasoning.
;)

> >> I happen to agree that most classes should have
> >> comments (and there are definitely various classes in m17n which may not 
> >> be
> >> obvious to the un-initiated) but the way to make your statement in a way
> >> that doesn't get lost is simply that: File a bug report.
> >
> > How can you say "most classes"? :) For which class would a MISSING class
> > comment be better than a SINGLE LINE class comment? I am truly curious.
> 
> There is no situation where no class comment would be "better" than a single 
> line comment. However, there are situations where no class comment is 
> "equal" (good or bad) to a single line comment.

I disagree and I have explained why a few times. Once more:

A MISSING comment can either mean that the author is lazy, has forgotten
to read it or simply hates class comments. It can mean either thing. It
does NOT tell me that the class needs no comment. This means that a
single line comment like "This class comment intentionally left blank
because I truly can't come up with even a single bloody sentence
explaining what this object is - it is IMHO so utterly obvious so you
simply will have to figure it out yourself stupid." - is immensely
better.

Why is it better? Because it tells me the intention. Ok, the author
thinks it is obvious and he hasn't forgotten to write the class comment.
Ok, then perhaps I dare reading the code and figure it out myself even
if it bugs me like hell that if it really IS so bloody obvious why can't
he bother to WRITE IT DOWN in the damn class comment?!?

Sigh. Ok, enough. Calm down, count to 10... Ok. calm.

> Take a look at the m17n text 
> converters for example - unless you want to go into a detailed description 
> about each format what would a one line comment say besides "I am a text 
> converter to/from yaddaya" and that much is really clear from looking at the 
> class. The same for the language environments and the encodings - I don't 
> see much value in a single line comment. (btw, having said that I wouldn't 
> mind that single line comment either)

Well, I hope I explained it in excrutiating detail above.

> Cheers,
>   - Andreas

regards, Göran