On Wed, 12 Sep 2007 15:49:44 -0700, Andreas Raab <andreas.raab at gmx.de>  
wrote:

> The trouble with your argumentation is that you assume one only has  
> "business" with a class if one knows it already.

Not a correct phrasing of my point: One has business with a class if one  
understands what it is meant to model. It is not Fraction's job to educate  
would-be-users on the purpose of fractions. If you take the viewpoint that  
it is, you will fail both to explain fractions and to explain the code.

> In which case I'd agree that comments are generally unnecessary because  
> you know about it already so what would be the point. However, generally  
> speaking this is only ever true for a single person - he who writes the  
> code in the first place.

If "numerator" and "denominator" serve the expected purpose of a fraction,  
it's counter-productive to comment them. Do you see that there's a  
difference between any given body of code and the thing it's attempting to  
model? Where "Fraction" needs to be documented is those places where the  
model deviates. Let's say, if you could silently set the denominator to  
zero, which might violate the custom of invoking ZeroDivide.

> The second, or third person will not have the intricate knowledge that  
> makes comments unnecessary - I see this every day in our own code, even  
> in areas where I'm pretty familiar with the underlying reality. The  
> comment I quoted from our code base *was* helpful for me because it  
> documented something about the usage that otherwise I would have had to  
> spend time in the tools to reverse engineer its implications.

And how exactly are you able to avoid reverse engeineering the Fraction  
class with this: "Integer - The number of parts in a fraction (written  
above the line of a fraction). See also denominator."? I've documented  
processes that are complicated enough to where I kept my own documentation  
at hand to refer to; I'm not denying such things exist. But there should  
be no requirement for code comments to serve as a cheat sheet, and to the  
extent that it does you will get comments that go stale faster and fewer  
quality comments overall.

> The fraction case is interesting for yet another reason: Fraction  
> (contrary to your contrived precinct example) is a real class in the  
> Squeak core.

There's nothing contrived about my precinct example: It's drawn from one  
of many very real experiences of having to decide where to draw the line  
on documentation. Code comments are about how and why =code= works, not  
why and how the =world= works.

> We can expect that a *lot* of people, regardless of whether their  
> background is mathematics or art, whether professional programmer,  
> retired or in school will look at it. Do you really think that, for all  
> of these audiences, having no comment is better than the comments I  
> provided?

Yes. For two reasons:

1. For someone who doesn't know what a fraction is, your comment is  
meaningless. Parts of what? What line?

2. For someone who does know what a fraction is, your comment is worse  
than meaningless: It forces them to stop and interpret that what you wrote  
actually means "numerator".

Squeak is full of these facile and largely usless comments like "Answer  
the sum of the receiver and aNumber" for "+" in the Number class, or even  
better, the Integer "+" which refers you to the worthless comment in  
Number. Nothing about normalization.

Your comment metrics are about as useless as a lines-of-code metric.

I'm all for comments. I'm not for a mad rush to put in meaningless stubs  
everywhere.