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.