OrderedCollection new allButLast?

Hi -

I just noticed that "OrderedCollection new allButLast" reacts very
different to, say, "Array new allButLast". And I'm wondering whether we
expect that effect from OrderedCollection?

Cheers,
   - Andreas

The class documentation should say what the intention of the class is.

"THIS CLASS HAS NO COMMENT!"

Hmm, lets look at the method.  Nope, no comment their either.

Shrug, who knows what it's supposed to do? :P

(Pet peeve of mine working with Squeak for awhile now <g>)

On Sep 11, 2007, at 4:57 PM, Andreas Raab wrote:

On 11-Sep-07, at 5:26 PM, Steven W Riggins wrote:

> The class documentation should say what the intention of the class is.
>
> "THIS CLASS HAS NO COMMENT!"
We really should change that to something more like
     "This comment has no class"
in a very ugly flashing, smelly, noisy font.

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Semolina - a  system of signalling with pudding.

Steven W Riggins wrote:
> The class documentation should say what the intention of the class is.
>
> "THIS CLASS HAS NO COMMENT!"
>
> Hmm, lets look at the method.  Nope, no comment their either.
>
> Shrug, who knows what it's supposed to do? :P
>
> (Pet peeve of mine working with Squeak for awhile now <g>)

I'm sure you'll enjoy this little rant then:

http://lists.squeakfoundation.org/pipermail/seaside/2007-March/011443.html

Cheers,
   - Andreas

On Sep 11, 2007, at 6:13 PM, Andreas Raab wrote:

Heh, my code is not much better, but that does not mean I can't work  
for improvement.

I think what I've noticed, being an "outsider" these last few years  
(outside of the smalltalk community) is that there appears to be this  
mentality that because the methods are short, they are self  
defining.  "See the code"

The problem I have run into is that code defines what the method  
does, not what the method was intended to do.

Then I am left being a spaghetti programmer, not much unlike my BASIC  
days of 1985, to unwind code paths and try to figure out how a method  
is being *used* to see if the method is doing what the callers  
*think* the method should be doing.

So what has happened is:

* Spend 6 hours figuring a method out, what it does, etc
* Talk to the engineer about it saying "it does this"
* "Oh damn, it should not be doing that, it should do this other thing"
* Fix the method in 5 minutes or less.

This is not worse than my objective-c Cocoa projects, mind you,  
finding Apple docs is better these days with the built in tools, but  
because the squeak browser makes it so easy to see class comments,  
and see a individual method's source, having a short 1 or 2 line  
comment about *intention* would just be fantastic.

This is similar to using s-units to develop code (hi john) which we  
on the Sophie team have been awful at (hi john), but the concept as  
you know is to define what the method should do, then implement the  
test, then implement the method.

Likewise, I feel every method should start with a comment, and this  
nonsense about the method selector being good enough to define  
intention just tossed out of the equation.  Show me a party where you  
can pass 1-4 words between 15 people and get the same 1-4 words at  
the end. :)  However, several sentences can be better, or not  
depending on the engineer, but at least it is a start.

Thus, I would ask that if this is not being done now, I'd ask people  
to evaluate this concept and look at their code from another  
developer's eyes, and hopefully understand that a statement of  
intention should be the first 'code' written for any method.

Steve

Steven W Riggins wrote:
> Likewise, I feel every method should start with a comment, and this
> nonsense about the method selector being good enough to define intention
> just tossed out of the equation.  Show me a party where you can pass 1-4
> words between 15 people and get the same 1-4 words at the end. :)  
> However, several sentences can be better, or not depending on the
> engineer, but at least it is a start.

Amen, brother.

Cheers,
   - Andreas

(In the interests of full disclosure I should point out that I work  
with Steve on the staggeringly wonderful www.sophieproject.org and  
that we have had this conversation many times)

On 11-Sep-07, at 7:16 PM, Steven W Riggins wrote:

>
> The problem I have run into is that code defines what the method  
> does, not what the method was intended to do.

This seems to be the crucial point that so many "read the code"  
bigots miss. Reading the code only tells you what it does and tells  
you *nothing* about what the original writer and any subsequent  
editors intended it to do, let alone what they didn't want it to do.  
I'll not bother to grouch about how many people write such awfully  
nasty code that even after tracing it through a debugger you still  
have no clue what is actually happening.

>
> Thus, I would ask that if this is not being done now, I'd ask  
> people to evaluate this concept and look at their code from another  
> developer's eyes, and hopefully understand that a statement of  
> intention should be the first 'code' written for any method.
Exactly. Even when you are doing exploratory programming, hacking out  
code, 'in the zone' or whatever excuse you make in your feeble  
attempts to get away with being incompetent you should note some  
semblance of a spec for  the method. At least explain what you  
thought it needs to do. Preferably include a few words about known  
limitations  (like "use a linear search in an array to find all  
solutions to the dymaxxion thumb-twiddler polynomial; note that this  
will not scale well beyond a few entries") and ideally comment on any  
unknown bugs.

People have written about "Literate Programming" - Don Knuth and  
Adele Goldberg for example - for years. Dan Lanovaz has coined the  
neat description/rallying cry "Don't document the program, program  
the document!" Please, try to remember that 20 minutes after you have  
written the code you are going to be diverted by some interesting bit  
of porn-spam and when you finally get back to it you will have  
forgotten what that 'totally obvious and no comment needed' bit of  
code is about.

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Press [ESC] to detonate or any other key to explode.

I've always started with the documentation.

But I'm not a big code commenter. I try to set up a system with documented  
rules and then just document the exceptions, along with an over-arching  
class comment. (And, if God help me, I have to write something clever,  
I'll document the bejeezus out of it.) On the other hand, doing it  
robotically is of little use.

E.g., does this really help:

at: key
        "Answer the value associated with the key."
        ^ self at: key ifAbsent: [self errorKeyNotFound]

? I mean, I should hope that's what it does.

But I don't disagree with what's being said. The problem is you very often  
have neither a cohesive system with documented rules, documented  
exceptions, nor class comments.

        ===Blake===

It truly is annoying when you look at classes with no comments.
Writers of classes need to remember that the next person looking at
the code doesn't have the whole architecture in their head like you do
so they may not know where to start.

But "every method should" is an exaggeration, no?  I mean do you want
a comment for every accessors saying "this is an accessors"?

In any event, Squeak could certainly use more commenting.

On 9/12/07, Andreas Raab <[hidden email]> wrote:

> This is similar to using s-units to develop code (hi john) which we  
> on the Sophie team have been awful at (hi john), but the concept as  
> you know is to define what the method should do, then implement the  
> test, then implement the method.

Dreadful... dreadful, still we've a few hundred tests to poke at  
textual context trees and to ensure data stuffed into the book  
storage layer is accessible and meets the documented APIs...  Thus no  
data corruption issues using the basic APIs

--
========================================================================
===
John M. McIntosh <[hidden email]>
Corporate Smalltalk Consulting Ltd.  http://www.smalltalkconsulting.com
========================================================================
===

Jason Johnson wrote:
> It truly is annoying when you look at classes with no comments.
> Writers of classes need to remember that the next person looking at
> the code doesn't have the whole architecture in their head like you do
> so they may not know where to start.
>
> But "every method should" is an exaggeration, no?  I mean do you want
> a comment for every accessors saying "this is an accessors"?

No, it should say what the variable is good for. We had this discussion
here recently and I have to admit that there is something to be said for
putting variable comments into the accessors instead of the class
comment (where they are much harder to find and to update). In an
optimal solution these would be automatically synchronized so the
comment of the accessors would be  the comments of the variable and vice
versa. Here is a good example from our code base:

cacheLocally
        "Boolean - if true, tells the system to maintain a locally cached copy
of the document file."
        ^ cacheLocally

Cheers,
   - Andreas

Ah, well that is a good point.

On 9/12/07, Andreas Raab <[hidden email]> wrote:

On 11-Sep-07, at 9:57 PM, Jason Johnson wrote:

> It truly is annoying when you look at classes with no comments.
> Writers of classes need to remember that the next person looking at
> the code doesn't have the whole architecture in their head like you do
> so they may not know where to start.
And to repeat repeat myself again again, the original writer won't  
have it all in her head after a distraction.
Or a few weeks. Or a vacation.

>
> But "every method should" is an exaggeration, no?  I mean do you want
> a comment for every accessors saying "this is an accessors"?
Actually in general I *do* want a comment in accessors; not a simple  
minded one though. Y'see I don't *like* simple accessors. Instance  
variables are there for a reason and they're not publicly accessible  
for another reason.A method that opens up my object to rape and  
pillage damn well *should* be commented. A class where all the  
instvars have accessors is generally going to be horribly abused. I  
mean, what is this ? C++? Gimme a break. People will be trying to  
tell me that Squeak must have an "access path notation for variable  
members" next. If I'm supposed to be exposing my programmatic  
buttocks to the world I want a  comment to explain why!


tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: CSF: Charge to NSF

Well, this brings up a good point.  After using Smalltalk for a while
I actually *do* feel that the language is somewhat "self documenting"
(i.e. it reads often like english).  But there are 2 places that the
code can't help with documentation; (1) why did you do this? and (2)
why did you change it from what you had before?

In the first case nothing can help but a comment.  In the second case
the tools, e.g. ChangeSet can show us *what* was done before, but I
think we need a way to add comments to change sets to explain *why* it
was changed at all.  Without this, people will look at the old version
and say "hrm, why did this guy change it?  The older version looks
obviously better" and off they go to relive old mistakes.  Or maybe
something has changed and the old way should be used again, but you
can't know without some kind of comment.

On 9/12/07, tim Rowledge <[hidden email]> wrote:

On Sep 11, 2007, at 10:59 PM, Jason Johnson wrote:

> (2)
> why did you change it from what you had before?
>

Yep, you get alittle bit of this from code control, but not always  
(people check in massive sets of changes)

If I had the skillz/time, I would have a development system that  
integrated the changes system, and monticello (with many  
improvements) and the browser.

1) You can't make a class without a comment.  sorry
2) You can't save a method without a comment.  sorry  The comments  
would be stored with the changes info
3) the source system would implement moderation automatically.  So  
developer A checks  chnages into the repository, but they are  
automatically marked as needing moderation (much like a blog).  
Moderator says "hey, 'cuz I could' is not a valid comment" and clicks  
reject"  Developer gets email saying so sad, so bad.  Maybe  
developer's boss, too.  the entire checkin is put on hold until that  
method is fixed, and all subsequent checkins are on hold too.  Really  
puts the importance on the comments and penalizes the lazy people  
severely.

:)

On Tue, 11 Sep 2007 22:19:17 -0700, tim Rowledge <[hidden email]> wrote:

That sounds good.

But, really, how do you apply it in practice to something like the read  
accessors to "numerator" and "denominator" in Fraction?

Some accessors really are both necessary, simple and not needing  
documentation.

Looks like a problem with SequenceableCollection>>#copyFrom:to:

Boils down to copyFrom: 1 to: -1
I would *expect* it to return an empty instance of the species (since
copyFrom: 1 to: 0 would).

RunArray and OrderedCollection both make a check that provides this
behaviour.

Il giorno mar, 11/09/2007 alle 23.03 -0700, Steven W Riggins ha
scritto:
> >
>
> That is excellent, especially adding the type in a typeless language.
> I can't tell you how many times I've been burned by this, or just sit
> in the debugger looking to see what might pass through :)

Wasn't there a plan to connect RoelTyper with the browser?

        Giovanni

Note that anybody can add comments to Squeak, just like anybody can
change code.  If you think that some code needs comments, write them
and post them as a change to Mantis.  In the Mantis issue, indicate
that you are only changing comments.

-Ralph