Comments
nice
ncellier at ifrance.com
Wed Sep 12 18:35:11 UTC 2007
Agree with Blake, too many comments kill the comments
While you are at updating the tools, put a href on webster site,
wikipedia or something in Fraction (class) comment.
Nicolas
Blake a écrit :
> 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.
>
>
More information about the Squeak-dev
mailing list
|