OrderedCollection new allButLast?

On Wed, 12 Sep 2007 15:49:44 -0700, Andreas Raab <[hidden email]>  
wrote:

> The trouble with your argumentation is that you assume one only has  
> "business" with a class if one knows it already.

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.

> In which case I'd agree that comments are generally unnecessary because  
> you know about it already so what would be the point. However, generally  
> speaking this is only ever true for a single person - he who writes the  
> code in the first place.

If "numerator" and "denominator" serve the expected purpose of a fraction,  
it's counter-productive to comment them. Do you see that there's a  
difference between any given body of code and the thing it's attempting to  
model? 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.

> The second, or third person will not have the intricate knowledge that  
> makes comments unnecessary - I see this every day in our own code, even  
> in areas where I'm pretty familiar with the underlying reality. The  
> comment I quoted from our code base *was* helpful for me because it  
> documented something about the usage that otherwise I would have had to  
> spend time in the tools to reverse engineer its implications.

And how exactly are you able to avoid reverse engeineering the Fraction  
class with this: "Integer - The number of parts in a fraction (written  
above the line of a fraction). See also denominator."? I've documented  
processes that are complicated enough to where I kept my own documentation  
at hand to refer to; I'm not denying such things exist. But there should  
be no requirement for code comments to serve as a cheat sheet, and to the  
extent that it does you will get comments that go stale faster and fewer  
quality comments overall.

> The fraction case is interesting for yet another reason: Fraction  
> (contrary to your contrived precinct example) is a real class in the  
> Squeak core.

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.

> We can expect that a *lot* of people, regardless of whether their  
> background is mathematics or art, whether professional programmer,  
> retired or in school will look at it. Do you really think that, for all  
> of these audiences, having no comment is better than the comments I  
> provided?

Yes. For two reasons:

1. For someone who doesn't know what a fraction is, your comment is  
meaningless. Parts of what? What line?

2. For someone who does know what a fraction is, your comment is worse  
than meaningless: It forces them to stop and interpret that what you wrote  
actually means "numerator".

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.

Your comment metrics are about as useless as a lines-of-code metric.

I'm all for comments. I'm not for a mad rush to put in meaningless stubs  
everywhere.

On 9/13/07, Blake <[hidden email]> wrote:
> On Wed, 12 Sep 2007 15:49:44 -0700, Andreas Raab <[hidden email]>
> 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.

On 9/13/07, Michael van der Gulik <[hidden email]> wrote:
>
> These should be compiler warnings, not errors. Not all methods and classes
> need comments.

Methods sure, but classes?  What reason is there to not have a comment
in a class?  You may think the class is obvious, but it should at
least point to the comment of another class that explains the
architecture of the package, and the entry point to using it.

The hardest time I have with Squeak's lack of documentation is when I
try to use a new package.  The class I happen to click on never has a
comment, I have no idea how the package is supposed to be used.  Some
say look at the tests for this, but tests should test everything,
including "private" methods that don't otherwise get called from
clients of the package.

Jason Johnson a écrit :
Yes, that's what i asked.
But then, we can also add information in class side specific to the
implementation like the Fraction will always be reduced (or tell when
not), that a minus sign should always be in the numerator etc...

Nicolas

it would be nice to have a consistent behavior.
Did somebody check the ANSI and VW behavior?

Stef

On 12 sept. 07, at 11:00, Gary Chambers wrote:

2007/9/13, stephane ducasse <[hidden email]>:
> it would be nice to have a consistent behavior.
> Did somebody check the ANSI

> and VW behavior?

VW is same as Squeak.
GST doesn't have #allButLast

Cheers
Philippe

Philippe Marschall a écrit :
Yes but in gst

Array new copyFrom: 1 to: -1!
Array new: 0 "<0x4058e2c0>"

So allButLast would not raise an Exception if implemented the same.

Nicolas

> So allButLast would not raise an Exception if implemented the same.

I just fixed it for 2.95d.  It now raises an exception.

#copyFrom: accepts a parameter which is 1 <= start <= size+1.

#copyFrom:to: accepts parameters which are 1 <= start <= size+1 and
start-1 <= stop <= size.

Paolo

stephane ducasse wrote:
> it would be nice to have a consistent behavior.
> Did somebody check the ANSI and VW behavior?

ANSI says it is an error if:
   stop >= start and (start < 1 or start > the receiver's size).
   stop >= start and (stop < 1 or stop > the receiver's size).

i.e., any value for which stop < start is valid and should return an
empty collection.  Whether #allButLast should behave the same, I won't say.

Paolo

On Wed, 12 Sep 2007 10:09:23 -0700, Andreas Raab
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.

---

Don't let your dream ride pass you by. Make it a reality with Yahoo! Autos.