<example> pragmas and example* methods use-cases
Locked
<example> pragmas and example* methods use-cases
 
|
Hi,
there was a long discussion about the meaning of example* methods and <example> pragmas, however I do not know what was the final resolution. Basically I am interested in two use-cases 1. executable example (the one where Nautilus shows nice play icon) This is as I understand only through example* naming (on class-side). 2. returning examples (example that returns some value that I can reuse) Is this what <example> pragma is for? How would I go about naming it considering that having play icon there would be counter-productive (user would be clicking on it and nothing would happen). Thanks, Peter |
Re: <example> pragmas and example* methods use-cases
|
|
2015-06-22 12:03 GMT+02:00 Peter Uhnák <[hidden email]>:
Yes, but I would like to use a pragma again and don't rely naming convention, we just wasn't able to agree on one.
Inspector and spotter use gtExample* names in addition to an <gtExample> pragma. <gtExample> -> for finding those methods gtExample*name -> for not getting the play icon. This is less than perfect.
|
|
|
I'll revisit my previous suggestion. In real life...
* a "sample" is a real object you can hold. You ask a supplier to "send you a sample" of their product so you can inspect it before you buy lots. In an industrial factory, you "take a sample" to take an item from the process stream to the lab to analyse. Both of these are real objects you can hold. In addition, Digital Signal Processing does sampling, it doesn't do exampling. * an "example" is one step removed from real life objects. The maths teacher works through an example. Someone's behaviour can set a good example. A programming script can provide an example of how to do something. People say "for example, how about my hypothetical** situation". None of these refer to a real object. Now you can use "example" to refer to real objects, but usually second hand when you are describing a general characteristic. It doesn't have the same concrete semantic of a real object as "sample". There were other suggestions that were reasonable. It might be better to have one pragma that is parameterized by what sort of example it is. cheers -ben ** Consider for a moment, what would the world be like without hypothetical situations? On Mon, Jun 22, 2015 at 6:49 PM, Nicolai Hess <[hidden email]> wrote: > > > 2015-06-22 12:03 GMT+02:00 Peter Uhnák <[hidden email]>: >> >> Hi, >> >> there was a long discussion about the meaning of example* methods and >> <example> pragmas, however I do not know what was the final resolution. >> >> Basically I am interested in two use-cases >> >> 1. executable example (the one where Nautilus shows nice play icon) >> This is as I understand only through example* naming (on class-side). > > > Yes, but I would like to use a pragma again and don't rely naming > convention, we just wasn't able to agree on one. > >> >> >> 2. returning examples (example that returns some value that I can reuse) >> Is this what <example> pragma is for? How would I go about naming it >> considering that having play icon there would be counter-productive (user >> would be clicking on it and nothing would happen). > > > Inspector and spotter use gtExample* names in addition to an <gtExample> > pragma. > <gtExample> -> for finding those methods > gtExample*name -> for not getting the play icon. > > This is less than perfect. > >> >> >> Thanks, >> Peter > > |
Re: <example> pragmas and example* methods use-cases
|
|
Ben Coman <[hidden email]> writes: > I'll revisit my previous suggestion. In real life... > > * a "sample" is a real object you can hold. You ask a supplier to > "send you a sample" of their product so you can inspect it before you > buy lots. In an industrial factory, you "take a sample" to take an > item from the process stream to the lab to analyse. Both of these are > real objects you can hold. In addition, Digital Signal Processing > does sampling, it doesn't do exampling. > > * an "example" is one step removed from real life objects. The maths > teacher works through an example. Someone's behaviour can set a good > example. A programming script can provide an example of how to do > something. People say "for example, how about my hypothetical** > situation". None of these refer to a real object. Now you can use > "example" to refer to real objects, but usually second hand when you > are describing a general characteristic. It doesn't have the same > concrete semantic of a real object as "sample". I like this vocabulary. -- Damien Cassou http://damiencassou.seasidehosting.st "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill |
Re: <example> pragmas and example* methods use-cases
|
|
In reply to this post by Nicolai Hess
Hi,
We are working on a more elaborate model for examples, but we need a bit more time to get to a rounder solution. Cheers, Doru On Mon, Jun 22, 2015 at 12:49 PM, Nicolai Hess <[hidden email]> wrote:
|
Re: <example> pragmas and example* methods use-cases
|
|
Thank you all for your answers (For whatever reason all replies by Torsten to this thread ended up as separate threads.. maybe mail client issues?) It seems that <sample> is then the go-to naming for now. I also like that the word starts differently so it's easy to differentiate them at a glance. On Mon, Jun 22, 2015 at 5:17 PM, Torsten Bergmann <[hidden email]> wrote: It is important to note that these methods COULD BUT I'm not sure I understand the purpose of this restriction. For example BorderedMorph>>exampleGradient could on top of opening a morph also return the instance. If you are running it from Nautilus it makes no difference, but when you run it manually you could also inspect the instance, so you could further manipulate with it... in a sense two-in-one. :) Otherwise you would have to get it via inspecting morph halos. Or in another sense you could either inspect <sample> and then manually run it, or execute <example> that would on top of that also return inspectable value of the <sample>. 2. returning examples Urban dictionary defines <exemplar> as "a typical or standard model or specimen" As a side note... I think it's best to use urban dictionary for slang, and not Pharo dev. :) Looking up the name of it there shows at least a bit of self-reflection. :) Peter |
|
|
On Tue, Jun 23, 2015 at 6:13 AM, Peter Uhnák <[hidden email]> wrote:
> Thank you all for your answers (For whatever reason all replies by Torsten > to this thread ended up as separate threads.. maybe mail client issues?) > > It seems that <sample> is then the go-to naming for now. I also like that > the word starts differently so it's easy to differentiate them at a glance. We should also see what Doru comes up with. > > > On Mon, Jun 22, 2015 at 5:17 PM, Torsten Bergmann <[hidden email]> wrote: >> >> It is important to note that these methods COULD BUT >> MUST NOT RETURN an instance. Usually such a method is only there to >> demonstrate code. > > > I'm not sure I understand the purpose of this restriction. For example > BorderedMorph>>exampleGradient could on top of opening a morph also return > the instance. > If you are running it from Nautilus it makes no difference, but when you run > it manually you could also inspect the instance, so you could further > manipulate with it... in a sense two-in-one. :) > Otherwise you would have to get it via inspecting morph halos. > > Or in another sense you could either inspect <sample> and then manually run > it, or execute <example> that would on top of that also return inspectable > value of the <sample>. > > >> 2. returning examples >> ===================== >> While some example methods just demo code and code usage (like "Job >> example" or "BorderedMorph exampleGradient") >> a subset of them directly return an instance of the method defining >> class (like LabelMorph>>example). >> >> The idea of the GT Tools is to call these methods and display the return >> value as inspectable "instances" in the tools, >> so for instance if you inspect class VirtualMachine or Character you get >> a tab entitled "E.g." where you can click on >> these sample instances. >> >> GT and (because GT )now latest Pharo currently still uses "gtExample" >> method prefix or <gtExample> pragma to mark such methods and there >> is also to wish to remove the "gt" prefix. But with this we would have a >> clash with the other "exampleXXX" usage. >> >> => I would propose to mark the code examples that return an instance >> with an <exemplar> method. >> >> According to Google definition of <exemplar> noun - "a person or >> thing serving as a typical example or excellent model." > > >> >> Urban dictionary defines <exemplar> as "a typical or standard model >> or specimen" > > > As a side note... I think it's best to use urban dictionary for slang, and > not Pharo dev. :) Looking up the name of it there shows at least a bit of > self-reflection. :) Good idea, but even this can be misleading and the usual wiki concerns with apply. While (b) seems reasonable, (a) and (c) are very suspect. Note the author "placefake." http://www.urbandictionary.com/define.php?term=exemplar (a) the mythical task occupying any computer technician, preferably employed by a university or other educational institute, for their summer months of 'down time.' (b) a typical or standard model or specimen: (i.e. and example. just said with a really dorky 15th century word.) (c) any action performed by don swanner. by placefakeJune 04, 2010 cheers -ben |
Re: <example> pragmas and example* methods use-cases
|
Administrator
|
In reply to this post by Peter Uhnak
I agree with Ben that from a native English perspective, exemplar doesn't quite sound right. Sample and Example are the two words that most clearly capture the intent. The problem with using #sample to return instances and #example to illustrate usage is that it's a bit too subtle. Even though technically one could argue the logic of that distinction, in reality English speakers use them interchangeably and it will be confusing. A core principle of Smalltalk is to type a bit more to make things clearer (e.g. avoid single-character/abbreviated variable names). I strongly feel we should be more specific and uniform by either using (<exampleInstance> & <exampleCode>) or (<sampleInstance> & <sampleCode>).
Cheers,
Sean |
Re: <example> pragmas and example* methods use-cases
|
|
2015-06-29 20:10 GMT+02:00 Sean P. DeNigris <[hidden email]>: Peter Uhnák wrote <sample> for example instances <demo> for examples opening a window or any other interaction ?
|
Re: <example> pragmas and example* methods use-cases
|
|
In reply to this post by Sean P. DeNigris
On 29-06-15 20:10, Sean P. DeNigris wrote:
> I strongly feel we should be > more specific and uniform by either using (<exampleInstance> & > <exampleCode>) or (<sampleInstance> & <sampleCode>). +1 Be specific. Stephan |
Re: <example> pragmas and example* methods use-cases
|
|
2015-06-30 9:09 GMT+02:00 Stephan Eggermont <[hidden email]>: On 29-06-15 20:10, Sean P. DeNigris wrote: +1 too
|
|
|
In reply to this post by Sean P. DeNigris
On Tue, Jun 30, 2015 at 2:10 AM, Sean P. DeNigris <[hidden email]> wrote:
> Peter Uhnák wrote >> It seems that >> <sample> >> is then the go-to naming for now > > I agree with Ben that from a native English perspective, exemplar doesn't > quite sound right. > > Sample and Example are the two words that most clearly capture the intent. > The problem with using #sample to return instances and #example to > illustrate usage is that it's a bit too subtle. Even though technically one > could argue the logic of that distinction, in reality English speakers use > them interchangeably and it will be confusing. Thats a fair argument. > A core principle of Smalltalk > is to type a bit more to make things clearer (e.g. avoid > single-character/abbreviated variable names). I strongly feel we should be > more specific and uniform by either using (<exampleInstance> & > <exampleCode>) or (<sampleInstance> & <sampleCode>). I find myself liking the last two, I think since the concatenated words rolls off the tongue nicer with one less syllable, but I think any of those are fine. Actually, rather than pairing based on the first part, maybe using <exampleCode> together with <sampleInstance> will distinguish the most between the two cases. cheers -ben |
Re: <example> pragmas and example* methods use-cases
|
Administrator
|
I agree that any of those would be fine. I kind of like your last suggestion, in fact.
Cheers,
Sean |
|
|
In reply to this post by Nicolai Hess
On 30/06/15 01:32, Nicolai Hess wrote:
I like this one. +1. Cheers, Offray |
|
|
In reply to this post by Sean P. DeNigris
2015-06-30 11:21 GMT-03:00 Sean P. DeNigris <[hidden email]>: Ben Coman wrote "Code" could mean anything. I would use: <exampleSmalltalkCode> <examplePharoCode> etc Hernán
|
«
Return to Pharo Smalltalk Users
|
1 view|%1 views
| Free forum by Nabble | Edit this page |