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