Comments

Jason Johnson jason.johnson.081 at gmail.com
Thu Sep 13 06:59:45 UTC 2007


On 9/13/07, Blake <blake at kingdomrpg.com> wrote:
> On Wed, 12 Sep 2007 15:49:44 -0700, Andreas Raab <andreas.raab at gmx.de>
> wrote:
>
> Not a correct phrasing of my point: One has business with a class if one
> understands what it is meant to model. It is not Fraction's job to educate
> would-be-users on the purpose of fractions. If you take the viewpoint that
> it is, you will fail both to explain fractions and to explain the code.

I would say you are both have good points.  In the case of fractions
they can appear when you might not be expecting them (e.g. 10 / 3) and
therefor may be encountered by little explorers who have learned
divide but not fractions.

On the other hand, it might be better served to put the comment at the
class level, i.e. "this is a fraction class.  for more information
about fractions follow <link>this link</link>.  This class conforms
completely to the mathematical description of a fraction".

> Where "Fraction" needs to be documented is those places where the
> model deviates. Let's say, if you could silently set the denominator to
> zero, which might violate the custom of invoking ZeroDivide.

This I agree with.  If you are documenting some domain class in a
situation where only people familiar with your domain will use the
class (Fraction probably doesn't fit this constraint) then it makes
sense to document only methods that deviate from what would be
expected.  Personally I see a method comment as "hey, something here
needs your attention".  Comments like the one in add below break that
trust.

> There's nothing contrived about my precinct example: It's drawn from one
> of many very real experiences of having to decide where to draw the line
> on documentation. Code comments are about how and why =code= works, not
> why and how the =world= works.

I would say comments should always explain why, and class comments
should summarize what.  Surely everyone would agree that commenting a
method to explain every step it is making is silly, as the code does
exactly that but in a more concise form (though it doesn't explain
dependencies or expectations).  An example, for me, of a really good
method comment is the byte code dispatcher.  It implements a binary
search to locate the correct operation for a given byte code and
clearly explains why that was done in the method.

> Squeak is full of these facile and largely usless comments like "Answer
> the sum of the receiver and aNumber" for "+" in the Number class, or even
> better, the Integer "+" which refers you to the worthless comment in
> Number. Nothing about normalization.

Yes, this comment does seem pretty useless.  Anyone who knows what
"sum" is will know what "+" is.



More information about the Squeak-dev mailing list