[squeak-dev] Hello / Quick Question

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

[squeak-dev] Hello / Quick Question

Casey Ransberger
Hello Squeakers!

I've been reading the list for a spell, I really love Squeak, and I've decided that I'd like to help out. I was wondering if there were any particular areas of the trunk that people thought could use a bit more testing (unit or otherwise.) Also, I get the impression that Squeak's in-image documentation is pretty weak in some spots. I have very little time to devote, so I thought that doing a spot of testing, or writing a class comment here or there might be a good way to do something small that still makes a difference.

Any recommendations?


Cheers,

Ron


Reply | Threaded
Open this post in threaded view
|

[squeak-dev] Re: Hello / Quick Question

Andreas.Raab
Ronald Spengler wrote:

> Hello Squeakers!
>
> I've been reading the list for a spell, I really love Squeak, and I've
> decided that I'd like to help out. I was wondering if there were any
> particular areas of the trunk that people thought could use a bit more
> testing (unit or otherwise.) Also, I get the impression that Squeak's
> in-image documentation is pretty weak in some spots. I have very little
> time to devote, so I thought that doing a spot of testing, or writing a
> class comment here or there might be a good way to do something small
> that still makes a difference.
>
> Any recommendations?

Good to see you ;-) Since Hannes just asked about it, how about you
check out Editor / TextEditor / SmalltalkEditor and write a few tests or
additional / improved comments. More importantly, what do you feel your
strengths are? Which areas do you feel particular comfortable with?

Cheers,
   - Andreas

Reply | Threaded
Open this post in threaded view
|

Re: [squeak-dev] Hello / Quick Question

David T. Lewis
In reply to this post by Casey Ransberger
On Tue, Aug 11, 2009 at 09:16:02PM -0700, Ronald Spengler wrote:
> Hello Squeakers!

Hello and welcome!

> I've been reading the list for a spell, I really love Squeak, and I've
> decided that I'd like to help out. I was wondering if there were any
> particular areas of the trunk that people thought could use a bit more
> testing (unit or otherwise.) Also, I get the impression that Squeak's
> in-image documentation is pretty weak in some spots. I have very little time
> to devote, so I thought that doing a spot of testing, or writing a class
> comment here or there might be a good way to do something small that still
> makes a difference.
>
> Any recommendations?

Pick something that you find personally interesting, and work on that.

Class comments are actually a very worthwhile contribution. It's
deceptively hard to write them, because you have to figure out the
original design intent of the author, then communicate it clearly
in a few words. But if you can do this well, a little bit of work
on making good class comments will be appreciated by thousands of
people who read them later on.

Another source of ideas is to browse though the bug reports on
Mantis at bugs.squeak.org. In many cases you can find an issue
where someone is looking for feedback or has a fix that needs to
be tested, or has a problem that needs a solution.

Dave


Reply | Threaded
Open this post in threaded view
|

[squeak-dev] Re: Hello / Quick Question

Simon Michael
Good morning Squeakers! Speaking of class comments, and now that there is a new committing process, I wanted to check
something: is it generally agreed that we'd like every class in the system commented ? Retroactively, if not when first
created ?

I can't think why not, but I'm asking since comment-less classes have persisted for such a long time.


Reply | Threaded
Open this post in threaded view
|

Re: [squeak-dev] Re: Hello / Quick Question

johnmci

On 12-Aug-09, at 9:20 AM, Simon Michael wrote:

> Good morning Squeakers! Speaking of class comments, and now that  
> there is a new committing process, I wanted to check something: is  
> it generally agreed that we'd like every class in the system  
> commented ? Retroactively, if not when first created ?
>
> I can't think why not, but I'm asking since comment-less classes  
> have persisted for such a long time.
>

Ooh I can't resist, I've the source code for sq3.10.2-7179web09.07.1  
as an iPhone ebook. Well actually it's a WikiServer image with a
bit of work to the code browser to make it work with Mobile Safari.

It has one 2 star comment

  "Many classes and methods don't have comments. Not so useful for  
newBs."


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





Reply | Threaded
Open this post in threaded view
|

Re: [squeak-dev] Re: Hello / Quick Question

Casey Ransberger
As the FNG, class comments are very important to me. I propose:

We should ship a release soon. That's maybe the most important thing in the universe right now. That said, as the FNG, I would like to propose a general standard:

- There should be an informative class comment for each class in the base image.
- Within reason, classes which are in the core image should have a comment written in a consistent style (e.g., "I represent...")
- It's okay to ship a release without meeting the above two objectives, as long as we make progress toward the above two objectives.

I personally would not mind wandering the image, looking for crappy or missing class comments, fixing them where I can, and asking the list for advice where I can't. I imagine that I could learn a lot that way:)

What do the lovely people of squeak-dev think?

  - Ron, the FNG

P.S.

For those not-in-the-know, the 'NG' in FNG stands for New Guy. I can't remember that the 'F' stands for.

On Wed, Aug 12, 2009 at 9:44 AM, John M McIntosh <[hidden email]> wrote:

On 12-Aug-09, at 9:20 AM, Simon Michael wrote:

Good morning Squeakers! Speaking of class comments, and now that there is a new committing process, I wanted to check something: is it generally agreed that we'd like every class in the system commented ? Retroactively, if not when first created ?

I can't think why not, but I'm asking since comment-less classes have persisted for such a long time.


Ooh I can't resist, I've the source code for sq3.10.2-7179web09.07.1 as an iPhone ebook. Well actually it's a WikiServer image with a
bit of work to the code browser to make it work with Mobile Safari.

It has one 2 star comment

 "Many classes and methods don't have comments. Not so useful for newBs."


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








Reply | Threaded
Open this post in threaded view
|

[squeak-dev] Re: Hello / Quick Question

Andreas.Raab
Ronald Spengler wrote:
> As the FNG, class comments are very important to me. I propose:
>
> We should ship a release soon. That's maybe the most important thing in
> the universe right now.

Personally I'm not in a hurry to finalize a new release. That's mostly
because I would like to concentrate on the contribution process for now
and make sure it's being accepted and the kinks worked out. Once we
start looking at release issues there will be a whole new set of issues
that I'd like to separate from the main contribution process.

> That said, as the FNG, I would like to propose a general standard:
>
> - There should be an informative class comment for each class in the
> base image.

I agree with this goal.

> - Within reason, classes which are in the core image should have a
> comment written in a consistent style (e.g., "I represent...")

I'm a bit hesitant on that one.

> - It's okay to ship a release without meeting the above two objectives,
> as long as we make progress toward the above two objectives.

Obviously. Having the above as requirements for a release makes little
sense.

> I personally would not mind wandering the image, looking for crappy or
> missing class comments, fixing them where I can, and asking the list for
> advice where I can't. I imagine that I could learn a lot that way:)
>
> What do the lovely people of squeak-dev think?

Sounds good. Give it a shot. Pick a package, work through the comments,
ask questions and see how people like the result. I recommend taking a
package that isn't too big and that fits your interests.

> For those not-in-the-know, the 'NG' in FNG stands for New Guy. I can't
> remember that the 'F' stands for.

Fancy. It stands for fancy.

Cheers,
   - Andreas

Reply | Threaded
Open this post in threaded view
|

[squeak-dev] Re: Hello / Quick Question

Simon Michael
Very good. Armed with a thumbs-up from both Andreas and the FNG, I too will try to submit a few class comments.


Reply | Threaded
Open this post in threaded view
|

Re: [squeak-dev] Re: Hello / Quick Question

Casey Ransberger
In reply to this post by Andreas.Raab
That's right! It was fancy... or feline? Something like that.

"Release soon" is, of course, my own thing. Sorry that I tried to sneak that in. My mom, see, she's having this problem that I don't really understand about blocks not being true closures? and I was hoping, well... my mother is a thundering tyrant and I'm afraid for my life. You understand.

I would like to retract my statement about consistent style in class comments. That's actually, thinking about it, asking waay too much. I should have thought about that before I said it. Having comments for each class in the first place would be a fabulous start.

I meant the original statement as kind of a gag, as if one reads between the lines, it really says: "Let's at least add one good comment before we ship it."

I know that if we put our heads together, I can pull that off!

 - Ron

On Wed, Aug 12, 2009 at 8:15 PM, Andreas Raab <[hidden email]> wrote:
Ronald Spengler wrote:
As the FNG, class comments are very important to me. I propose:

We should ship a release soon. That's maybe the most important thing in the universe right now.

Personally I'm not in a hurry to finalize a new release. That's mostly because I would like to concentrate on the contribution process for now and make sure it's being accepted and the kinks worked out. Once we start looking at release issues there will be a whole new set of issues that I'd like to separate from the main contribution process.


That said, as the FNG, I would like to propose a general standard:

- There should be an informative class comment for each class in the base image.

I agree with this goal.


- Within reason, classes which are in the core image should have a comment written in a consistent style (e.g., "I represent...")

I'm a bit hesitant on that one.


- It's okay to ship a release without meeting the above two objectives, as long as we make progress toward the above two objectives.

Obviously. Having the above as requirements for a release makes little sense.


I personally would not mind wandering the image, looking for crappy or missing class comments, fixing them where I can, and asking the list for advice where I can't. I imagine that I could learn a lot that way:)

What do the lovely people of squeak-dev think?

Sounds good. Give it a shot. Pick a package, work through the comments, ask questions and see how people like the result. I recommend taking a package that isn't too big and that fits your interests.


For those not-in-the-know, the 'NG' in FNG stands for New Guy. I can't remember that the 'F' stands for.

Fancy. It stands for fancy.

Cheers,
 - Andreas




Reply | Threaded
Open this post in threaded view
|

[squeak-dev] Re: Hello / Quick Question

Simon Michael
In reply to this post by Simon Michael
I added a class comment, fixed another and published the affected package (MorphicExtras) to source.squeak.org/inbox .
Now I'll wait for developments. A few comments on the process:

- it skipped a version number because I first tried publishing to the wrong repo, harmless I assume.

- it uploaded a full snapshot of the package. Hopefully when someone reviews it for trunk they'll see just the actual
changes.

- I found out what to do by scanning all recent mails from andreas. I hit all of the teething issues described in later
emails. When we gather the essential info and a nightly image on a squeak.org download page, that will make it really
easy for folks to jump in.


Reply | Threaded
Open this post in threaded view
|

[squeak-dev] Re: Hello / Quick Question

Andreas.Raab
Simon Michael wrote:
> I added a class comment, fixed another and published the affected
> package (MorphicExtras) to source.squeak.org/inbox . Now I'll wait for
> developments.

Great. It's already in the trunk. BTW, I'm not sure if people notice
that but with the latest browser changes, you get effectively the first
line of each comment visible when you click on the class definition.
This works very well in cases like your AlignmentMorphBob1 comment which
then just says:

"A quick and easy way to space things vertically in absolute or
proportional amounts."

Just about perfect for a one-line description of the class. I like it a
lot. I think we should try to have such a one-line description as the
first sentence in each comment, precisely intended to be shown in the
browser when a user clicks on that class. You get more detailed info
when looking at the comment explicitly, but the one-liner is nice.

> - it skipped a version number because I first tried publishing to the
> wrong repo, harmless I assume.

Completely harmless. This happens all the time.

> - it uploaded a full snapshot of the package. Hopefully when someone
> reviews it for trunk they'll see just the actual changes.

Yes. The merge browser shows only the changes, so it's straightforward
to see what has changed. Even better, since you based your version off
the latest trunk, I could just copy it into the trunk even without
explicitly merging and uploading (which makes the process a little easier).

> - I found out what to do by scanning all recent mails from andreas. I
> hit all of the teething issues described in later emails. When we gather
> the essential info and a nightly image on a squeak.org download page,
> that will make it really easy for folks to jump in.

Nice to see it was helpful to you.

Cheers,
   - Andreas

Reply | Threaded
Open this post in threaded view
|

[squeak-dev] Adding comments

Simon Michael
Thanks Andreas.

> that but with the latest browser changes, you get effectively the first
> line of each comment visible when you click on the class definition.

I'm guessing you mean that one line comment pane you get at the bottom
if the browsing -> annotationPanes preference is enabled.

> This works very well in cases like your AlignmentMorphBob1 comment which

I just added one word. I wanted to find out who wrote the original comment,
but here's an example of the second-class status of class comments I was talking about:
there's no ui-exposed way to see the history of anything but methods.

> lot. I think we should try to have such a one-line description as the
> first sentence in each comment

+1. Python has a similar policy and commenters may find their style guides worth a look:

http://www.python.org/dev/peps/pep-0008 -> Comments
http://www.python.org/dev/peps/pep-0257 -> Multi-line Docstrings


When I remember how much pain was involved in, eg, setting up nice fonts, having them magically arrive in the update
stream and just work was very nice. Ditto for manually pulling various package fixes from all over the place. I think
the new setup is a big step in making Squeak development fun again.


Reply | Threaded
Open this post in threaded view
|

[squeak-dev] Re: Adding comments

Simon Michael
Simon Michael wrote:
> but here's an example of the second-class status of class comments I was talking about:
> there's no ui-exposed way to see the history of anything but methods.

Ha, not quite true! With ? selected in the browser, click the versions button to see the class comment's history.

Reply | Threaded
Open this post in threaded view
|

Re: [squeak-dev] Re: Hello / Quick Question

Eliot Miranda-2
In reply to this post by Casey Ransberger


On Wed, Aug 12, 2009 at 9:28 PM, Ronald Spengler <[hidden email]> wrote:
That's right! It was fancy... or feline? Something like that.

"Release soon" is, of course, my own thing. Sorry that I tried to sneak that in. My mom, see, she's having this problem that I don't really understand about blocks not being true closures? and I was hoping, well... my mother is a thundering tyrant and I'm afraid for my life. You understand.

Tell her blocks are real closures now :)
 

I would like to retract my statement about consistent style in class comments. That's actually, thinking about it, asking waay too much. I should have thought about that before I said it. Having comments for each class in the first place would be a fabulous start.

I meant the original statement as kind of a gag, as if one reads between the lines, it really says: "Let's at least add one good comment before we ship it."

I know that if we put our heads together, I can pull that off!

 - Ron

On Wed, Aug 12, 2009 at 8:15 PM, Andreas Raab <[hidden email]> wrote:
Ronald Spengler wrote:
As the FNG, class comments are very important to me. I propose:

We should ship a release soon. That's maybe the most important thing in the universe right now.

Personally I'm not in a hurry to finalize a new release. That's mostly because I would like to concentrate on the contribution process for now and make sure it's being accepted and the kinks worked out. Once we start looking at release issues there will be a whole new set of issues that I'd like to separate from the main contribution process.


That said, as the FNG, I would like to propose a general standard:

- There should be an informative class comment for each class in the base image.

I agree with this goal.


- Within reason, classes which are in the core image should have a comment written in a consistent style (e.g., "I represent...")

I'm a bit hesitant on that one.


- It's okay to ship a release without meeting the above two objectives, as long as we make progress toward the above two objectives.

Obviously. Having the above as requirements for a release makes little sense.


I personally would not mind wandering the image, looking for crappy or missing class comments, fixing them where I can, and asking the list for advice where I can't. I imagine that I could learn a lot that way:)

What do the lovely people of squeak-dev think?

Sounds good. Give it a shot. Pick a package, work through the comments, ask questions and see how people like the result. I recommend taking a package that isn't too big and that fits your interests.


For those not-in-the-know, the 'NG' in FNG stands for New Guy. I can't remember that the 'F' stands for.

Fancy. It stands for fancy.

Cheers,
 - Andreas