[squeak-dev] Hello / Quick Question
Locked
[squeak-dev] Hello / Quick Question
 
|
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
|
[squeak-dev] Re: Hello / Quick Question
|
|
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 |
Re: [squeak-dev] Hello / Quick Question
|
|
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 |
[squeak-dev] Re: Hello / Quick Question
|
|
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. |
|
|
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 = = = ======================================================================== |
Re: [squeak-dev] Re: Hello / Quick Question
|
|
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:
|
[squeak-dev] Re: Hello / Quick Question
|
|
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 |
[squeak-dev] Re: Hello / Quick Question
|
|
Very good. Armed with a thumbs-up from both Andreas and the FNG, I too will try to submit a few class comments.
|
Re: [squeak-dev] Re: Hello / Quick Question
|
|
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:
|
[squeak-dev] Re: Hello / Quick Question
|
|
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. |
[squeak-dev] Re: Hello / Quick Question
|
|
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 |
|
|
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. |
[squeak-dev] Re: Adding comments
|
|
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. |
Re: [squeak-dev] Re: Hello / Quick Question
|
|
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. Tell her blocks are real closures now :)
|
«
Return to Squeak - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |