The trouble with your argumentation is that you assume one only has 
"business" with a class if one knows it already. 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. 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.

The fraction case is interesting for yet another reason: Fraction 
(contrary to your contrived precinct example) is a real class in the 
Squeak core. 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?

Cheers,
   - Andreas

Blake wrote:
> On Wed, 12 Sep 2007 10:09:23 -0700, Andreas Raab <andreas.raab at gmx.de> 
> wrote:
> 
>> Numerator and denominator are no such accessors for sure. First, they 
>> describe pretty complex objects and just because *you* know what these 
>> mean doesn't mean everybody else does. Secondly, the denominator has 
>> even exceptional conditions (like that it can't be zero) which is 
>> *most definitely* in need of commenting. I'm sorry but your example 
>> falls far short of the point you're trying to make.
> 
>     Disagreed. Unless you want to argue the position that part of the 
> Fraction class's responsibility is to teach someone who doesn't know 
> what a fraction is, what a fraction is. (In which case, I still disagree.)
> 
>     It's not just =me= who knows what they are, it's anyone who has any 
> business using the Fraction class. Your class comment for numerator and 
> denominator say nothing that isn't in the dictionary.
> 
>     Let me use a more obscure example: Say I create a voter database for 
> a registrar and I have a variable for the precinct that the voter is in. 
> Should I then, as an accessor comment, explain what a precinct is? Its 
> role in the electoral college? The history of gerrymandering?[1]
> 
>     It's not the job of code comments to explain reality, the language 
> of what being modeled, or common non-code abstractions (like fractions). 
> Code comments should explain where code diverges from reality, where the 
> variables used might be misleading, or where accepted abstractions are 
> changed. For example, SmallInteger and Large*Integer comments usefully 
> point out their limitations, which have nothing to do with the concept 
> of Integers. They don't explain WHY, and go into the concept of the 
> machine word, etc.
> 
>     Ultimately, it's all abstraction, which one could argue demands 
> explanantion of what is being modeled. But at some level, a programmer 
> says, "Yes, I know this variable 'pineapple' isn't =actually= a 
> pineapple, but it's convenient to pretend it is."
> 
>     If you comment EVERYTHING, you end up devaluing the comments that 
> are actually meaningful. And so, the one time the programmer is using 
> "pineapples" to mean "hand grenades" you miss it, because you've grown 
> accustomed to ignoring the comments, which are mostly noise. And from 
> what I've seen, code comment posses often end up adding a lot of noise 
> which is at best useless, and at worst, confusing.
> 
>     ===Blake===
> 
> [1] I have provided that sort of basic education in supporting documents 
> and occasionally even in class comments, but it shouldn't be mistaken 
> for any kind of =code= documentation, and is generally a poor substitute 
> for having actual education.
> 
>