blake at kingdomrpg.com
Wed Sep 12 19:27:46 UTC 2007
On Wed, 12 Sep 2007 10:09:23 -0700, Andreas Raab <andreas.raab at gmx.de>
> 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?
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
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.
 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.
More information about the Squeak-dev