a request to change the meaning of <example> pragma
Locked
a request to change the meaning of <example> pragma
 
|
Hi,
As you might know, a while ago we created GTExamples, a framework that supports both example-based live documentation and testing: http://gtoolkit.org/doc/Examples/examples.html GTExamples was part of the GTInspector for a while, but as it evolved, we pulled it out in a separate project. This separate project is not in Pharo anymore but it is part of the full GToolkit configuration (Pharo only ships the core of GToolkit). The idea of taking GTExamples out was to allow the community to have a more elaborate discussion about the role of examples in our environment. I have invited you to join that conversation, but it did not take off. I understand that perhaps the topic does not look appealing at this moment. We will certainly continue to evolve GTExamples both on the semantics level of the dependency constructs and on the integration with tools. Our goal is to enable a new practice that I would like to call Example-Guilded Development (or Example-Driven Development), and position Pharo to be the only platform on which someone can do that. But, that is our goal, and does not have to be the same with other people’s goal. Right now, GTExamples relies on the <gtExample> pragma to denote a method that returns an object that exemplifies something. Executing this method as an example should have no side-effects (either because the method itself does not have a side-effect, or because the example method defines how the cleanup should happen using the mechanism provided by GTExamples). This meaning is different from the meaning of the <example> pragma used through Pharo. There are currently 55 places that use this pragma inside Pharo and most of them come from FastTable. As things will progress and more libraries might use GTExamples, the situation can become confusing. To make things less confusing in the future, I would like to define the meaning of the <example> to denote a method that returns an object without having side effects. Would you agree with this? If yes, I would suggest the name of the new pragma that would replace the existing one to include “script” in the name. For example, <sampleScript>. What do you think? Cheers, Doru -- www.tudorgirba.com www.feenk.com "Reasonable is what we are accustomed with." |
Re: a request to change the meaning of <example> pragma
|
I would like an actual example to understand this, funny , I know
On Sun, 18 Dec 2016 at 23:50, Tudor Girba <[hidden email]> wrote: Hi, |
Re: a request to change the meaning of <example> pragma
|
|
In reply to this post by Tudor Girba-2
Is it possible to have examples in a 5.0? Phil On Sun, Dec 18, 2016 at 10:49 PM, Tudor Girba <[hidden email]> wrote: Hi, |
|
|
In reply to this post by Tudor Girba-2
On Mon, Dec 19, 2016 at 5:49 AM, Tudor Girba <[hidden email]> wrote:
> Hi, > > As you might know, a while ago we created GTExamples, a framework that supports both example-based live documentation and testing: > http://gtoolkit.org/doc/Examples/examples.html > > GTExamples was part of the GTInspector for a while, but as it evolved, we pulled it out in a separate project. This separate project is not in Pharo anymore but it is part of the full GToolkit configuration (Pharo only ships the core of GToolkit). The idea of taking GTExamples out was to allow the community to have a more elaborate discussion about the role of examples in our environment. > > I have invited you to join that conversation, but it did not take off. I understand that perhaps the topic does not look appealing at this moment. > > We will certainly continue to evolve GTExamples both on the semantics level of the dependency constructs and on the integration with tools. Our goal is to enable a new practice that I would like to call Example-Guilded Development (or Example-Driven Development), and position Pharo to be the only platform on which someone can do that. But, that is our goal, and does not have to be the same with other people’s goal. > > Right now, GTExamples relies on the <gtExample> pragma to denote a method that returns an object that exemplifies something. I've previously not done a good job of promoting the use of <sample> for this. I'll try spinning this wheel once more. There are two concepts to consider: * The returned object. * The method code that creates the returned object. The "returned object" is best considered a <sample>. The "method code" is best considered an <example> that produces the sample. http://www.differencebetween.com/difference-between-example-and-vs-sample/ The term "exemplifies/exemplification" associates equally with both... * http://www.thesaurus.com/browse/example * http://www.thesaurus.com/browse/sample but for example... from a draw full of cutlery you don't "take an example spoon", you "take a sample spoon". So it depends on where you want the focus to be. * If the focus is on working with a sample object, then <sample> makes a better pragma for the method creating it. * If the focus is on the code producing the sample, then <example> is a better choice. Maybe you are constrained by existing industry terminology, but "Example-Driven Development" might be equally called "Sample-Driven Development". Without having read into the topic, intuitively the former broadly encompasses copying static code while the latter feels more limited to working with an object. My proposal... * <sample> provides a narrower sense of side-effect-free provision of object to work with. "Samples are often tangible parts and can be observed" * <example> provides a broader sense of showing how things work together, in ways that may or may-not include side effects that you don't actually want to execute - just to refer to. "Examples are used [to] illustrate something. [Its] expected that the example will be imitated and replicated among its audience." * <script> provides a sense of system management, of methods causing significant side effects. You won't want to copy these methods, just make use them. <sampleScript> feels awkward to apply to examples, since by my these are neither samples nor scripts. cheers -ben > Executing this method as an example should have no side-effects (either because the method itself does not have a side-effect, or because the example method defines how the cleanup should happen using the mechanism provided by GTExamples). > > This meaning is different from the meaning of the <example> pragma used through Pharo. There are currently 55 places that use this pragma inside Pharo and most of them come from FastTable. As things will progress and more libraries might use GTExamples, the situation can become confusing. > > To make things less confusing in the future, I would like to define the meaning of the <example> to denote a method that returns an object without having side effects. Would you agree with this? > > If yes, I would suggest the name of the new pragma that would replace the existing one to include “script” in the name. For example, <sampleScript>. > > What do you think? > > Cheers, > Doru > > > -- > www.tudorgirba.com > www.feenk.com > > "Reasonable is what we are accustomed with." > > |
Re: a request to change the meaning of <example> pragma
|
|
In reply to this post by kilon.alios
Hi,
You can find the documentation including a tutorial in the link below. And of course, there are examples for examples in the code: http://gtoolkit.org/doc/Examples/examples.html Cheers, Doru > On Dec 18, 2016, at 10:55 PM, Dimitris Chloupis <[hidden email]> wrote: > > I would like an actual example to understand this, funny , I know > On Sun, 18 Dec 2016 at 23:50, Tudor Girba <[hidden email]> wrote: > Hi, > > As you might know, a while ago we created GTExamples, a framework that supports both example-based live documentation and testing: > http://gtoolkit.org/doc/Examples/examples.html > > GTExamples was part of the GTInspector for a while, but as it evolved, we pulled it out in a separate project. This separate project is not in Pharo anymore but it is part of the full GToolkit configuration (Pharo only ships the core of GToolkit). The idea of taking GTExamples out was to allow the community to have a more elaborate discussion about the role of examples in our environment. > > I have invited you to join that conversation, but it did not take off. I understand that perhaps the topic does not look appealing at this moment. > > We will certainly continue to evolve GTExamples both on the semantics level of the dependency constructs and on the integration with tools. Our goal is to enable a new practice that I would like to call Example-Guilded Development (or Example-Driven Development), and position Pharo to be the only platform on which someone can do that. But, that is our goal, and does not have to be the same with other people’s goal. > > Right now, GTExamples relies on the <gtExample> pragma to denote a method that returns an object that exemplifies something. Executing this method as an example should have no side-effects (either because the method itself does not have a side-effect, or because the example method defines how the cleanup should happen using the mechanism provided by GTExamples). > > This meaning is different from the meaning of the <example> pragma used through Pharo. There are currently 55 places that use this pragma inside Pharo and most of them come from FastTable. As things will progress and more libraries might use GTExamples, the situation can become confusing. > > To make things less confusing in the future, I would like to define the meaning of the <example> to denote a method that returns an object without having side effects. Would you agree with this? > > If yes, I would suggest the name of the new pragma that would replace the existing one to include “script” in the name. For example, <sampleScript>. > > What do you think? > > Cheers, > Doru > > > -- > www.tudorgirba.com > www.feenk.com > > "Reasonable is what we are accustomed with." > > -- www.tudorgirba.com www.feenk.com "The coherence of a trip is given by the clearness of the goal." |
Re: a request to change the meaning of <example> pragma
|
|
In reply to this post by philippeback
We did not try, but it should not be a problem, except for the fact that there will be a GTExample class in Pharo 5 packaged with GTInspector.
Cheers, Doru > On Dec 19, 2016, at 12:51 AM, [hidden email] wrote: > > Is it possible to have examples in a 5.0? > > Phil > > On Sun, Dec 18, 2016 at 10:49 PM, Tudor Girba <[hidden email]> wrote: > Hi, > > As you might know, a while ago we created GTExamples, a framework that supports both example-based live documentation and testing: > http://gtoolkit.org/doc/Examples/examples.html > > GTExamples was part of the GTInspector for a while, but as it evolved, we pulled it out in a separate project. This separate project is not in Pharo anymore but it is part of the full GToolkit configuration (Pharo only ships the core of GToolkit). The idea of taking GTExamples out was to allow the community to have a more elaborate discussion about the role of examples in our environment. > > I have invited you to join that conversation, but it did not take off. I understand that perhaps the topic does not look appealing at this moment. > > We will certainly continue to evolve GTExamples both on the semantics level of the dependency constructs and on the integration with tools. Our goal is to enable a new practice that I would like to call Example-Guilded Development (or Example-Driven Development), and position Pharo to be the only platform on which someone can do that. But, that is our goal, and does not have to be the same with other people’s goal. > > Right now, GTExamples relies on the <gtExample> pragma to denote a method that returns an object that exemplifies something. Executing this method as an example should have no side-effects (either because the method itself does not have a side-effect, or because the example method defines how the cleanup should happen using the mechanism provided by GTExamples). > > This meaning is different from the meaning of the <example> pragma used through Pharo. There are currently 55 places that use this pragma inside Pharo and most of them come from FastTable. As things will progress and more libraries might use GTExamples, the situation can become confusing. > > To make things less confusing in the future, I would like to define the meaning of the <example> to denote a method that returns an object without having side effects. Would you agree with this? > > If yes, I would suggest the name of the new pragma that would replace the existing one to include “script” in the name. For example, <sampleScript>. > > What do you think? > > Cheers, > Doru > > > -- > www.tudorgirba.com > www.feenk.com > > "Reasonable is what we are accustomed with." > > > -- www.tudorgirba.com www.feenk.com "There are no old things, there are only old ways of looking at them." |
Re: a request to change the meaning of <example> pragma
|
|
In reply to this post by Ben Coman
Hi,
I would prefer if this thread does not transform in a terminology debate too much. Example is a term that fits both the code and the returning object. <gtExample> is applied on a method and it primarily describes that method. The term “example” also describes the meta object that is wraps the concrete return value with the information from the method (for example, the label of the example, the link to the subject, or the dependencies to other examples). The example term is also important from the metaphor point of view: "we learn from examples”. Cheers, Doru > On Dec 19, 2016, at 3:34 AM, Ben Coman <[hidden email]> wrote: > > On Mon, Dec 19, 2016 at 5:49 AM, Tudor Girba <[hidden email]> wrote: >> Hi, >> >> As you might know, a while ago we created GTExamples, a framework that supports both example-based live documentation and testing: >> http://gtoolkit.org/doc/Examples/examples.html >> >> GTExamples was part of the GTInspector for a while, but as it evolved, we pulled it out in a separate project. This separate project is not in Pharo anymore but it is part of the full GToolkit configuration (Pharo only ships the core of GToolkit). The idea of taking GTExamples out was to allow the community to have a more elaborate discussion about the role of examples in our environment. >> >> I have invited you to join that conversation, but it did not take off. I understand that perhaps the topic does not look appealing at this moment. >> >> We will certainly continue to evolve GTExamples both on the semantics level of the dependency constructs and on the integration with tools. Our goal is to enable a new practice that I would like to call Example-Guilded Development (or Example-Driven Development), and position Pharo to be the only platform on which someone can do that. But, that is our goal, and does not have to be the same with other people’s goal. >> >> Right now, GTExamples relies on the <gtExample> pragma to denote a method that returns an object that exemplifies something. > > > I've previously not done a good job of promoting the use of <sample> > for this. I'll try spinning this wheel once more. > > There are two concepts to consider: > * The returned object. > * The method code that creates the returned object. > > The "returned object" is best considered a <sample>. > The "method code" is best considered an <example> that produces the sample. > http://www.differencebetween.com/difference-between-example-and-vs-sample/ > > The term "exemplifies/exemplification" associates equally with both... > * http://www.thesaurus.com/browse/example > * http://www.thesaurus.com/browse/sample > but for example... from a draw full of cutlery you don't "take an > example spoon", you "take a sample spoon". > > > So it depends on where you want the focus to be. > * If the focus is on working with a sample object, then <sample> makes > a better pragma for the method creating it. > * If the focus is on the code producing the sample, then <example> is > a better choice. > > Maybe you are constrained by existing industry terminology, > but "Example-Driven Development" might be equally called > "Sample-Driven Development". > Without having read into the topic, intuitively the former broadly > encompasses copying static code > while the latter feels more limited to working with an object. > > > My proposal... > * <sample> provides a narrower sense of side-effect-free provision of > object to work with. "Samples are often tangible parts and can be > observed" > * <example> provides a broader sense of showing how things work > together, in ways that may or may-not include side effects that you > don't actually want to execute - just to refer to. "Examples are used > [to] illustrate something. [Its] expected that the example will be > imitated and replicated among its audience." > * <script> provides a sense of system management, of methods causing > significant side effects. You won't want to copy these methods, just > make use them. > > <sampleScript> feels awkward to apply to examples, since by my these > are neither samples nor scripts. > > > cheers -ben > > >> Executing this method as an example should have no side-effects (either because the method itself does not have a side-effect, or because the example method defines how the cleanup should happen using the mechanism provided by GTExamples). >> >> This meaning is different from the meaning of the <example> pragma used through Pharo. There are currently 55 places that use this pragma inside Pharo and most of them come from FastTable. As things will progress and more libraries might use GTExamples, the situation can become confusing. >> >> To make things less confusing in the future, I would like to define the meaning of the <example> to denote a method that returns an object without having side effects. Would you agree with this? >> >> If yes, I would suggest the name of the new pragma that would replace the existing one to include “script” in the name. For example, <sampleScript>. >> >> What do you think? >> >> Cheers, >> Doru >> >> >> -- >> www.tudorgirba.com >> www.feenk.com >> >> "Reasonable is what we are accustomed with." -- www.tudorgirba.com www.feenk.com “Software has no shape. Actually, it has no one shape. It has many." |
Re: a request to change the meaning of <example> pragma
|
|
2016-12-19 8:46 GMT+01:00 Tudor Girba <[hidden email]>: Hi, @Doru, but you asked "What do you think" and I think Bens response about sampleScript is valid @Ben Did you check Dorus blog entry (http://gtoolkit.org/doc/Examples/examples.html) I think this makes it more clear why gttExamples are more than just methods producsing "samples" Example is a term that fits both the code and the returning object. <gtExample> is applied on a method and it primarily describes that method. The term “example” also describes the meta object that is wraps the concrete return value with the information from the method (for example, the label of the example, the link to the subject, or the dependencies to other examples). The example term is also important from the metaphor point of view: "we learn from examples”. |
Re: a request to change the meaning of <example> pragma
|
|
Hi,
> On Dec 19, 2016, at 8:53 AM, Nicolai Hess <[hidden email]> wrote: > > > > 2016-12-19 8:46 GMT+01:00 Tudor Girba <[hidden email]>: > Hi, > > I would prefer if this thread does not transform in a terminology debate too much. > > > @Doru, but you asked "What do you think" and I think Bens response about sampleScript is valid I did not say that he was wrong. I just expressed the wish to not transform the thread in a long debate :). I would still very much welcome the debate in a separate thread in which we can start from the existing GTExamples model and tare it apart to find something better. Cheers, Doru > @Ben Did you check Dorus blog entry (http://gtoolkit.org/doc/Examples/examples.html) I think this makes > it more clear why gttExamples are more than just methods producsing "samples" > > > Example is a term that fits both the code and the returning object. <gtExample> is applied on a method and it primarily describes that method. The term “example” also describes the meta object that is wraps the concrete return value with the information from the method (for example, the label of the example, the link to the subject, or the dependencies to other examples). The example term is also important from the metaphor point of view: "we learn from examples”. > > Cheers, > Doru > > > > > On Dec 19, 2016, at 3:34 AM, Ben Coman <[hidden email]> wrote: > > > > On Mon, Dec 19, 2016 at 5:49 AM, Tudor Girba <[hidden email]> wrote: > >> Hi, > >> > >> As you might know, a while ago we created GTExamples, a framework that supports both example-based live documentation and testing: > >> http://gtoolkit.org/doc/Examples/examples.html > >> > >> GTExamples was part of the GTInspector for a while, but as it evolved, we pulled it out in a separate project. This separate project is not in Pharo anymore but it is part of the full GToolkit configuration (Pharo only ships the core of GToolkit). The idea of taking GTExamples out was to allow the community to have a more elaborate discussion about the role of examples in our environment. > >> > >> I have invited you to join that conversation, but it did not take off. I understand that perhaps the topic does not look appealing at this moment. > >> > >> We will certainly continue to evolve GTExamples both on the semantics level of the dependency constructs and on the integration with tools. Our goal is to enable a new practice that I would like to call Example-Guilded Development (or Example-Driven Development), and position Pharo to be the only platform on which someone can do that. But, that is our goal, and does not have to be the same with other people’s goal. > >> > >> Right now, GTExamples relies on the <gtExample> pragma to denote a method that returns an object that exemplifies something. > > > > > > I've previously not done a good job of promoting the use of <sample> > > for this. I'll try spinning this wheel once more. > > > > There are two concepts to consider: > > * The returned object. > > * The method code that creates the returned object. > > > > The "returned object" is best considered a <sample>. > > The "method code" is best considered an <example> that produces the sample. > > http://www.differencebetween.com/difference-between-example-and-vs-sample/ > > > > The term "exemplifies/exemplification" associates equally with both... > > * http://www.thesaurus.com/browse/example > > * http://www.thesaurus.com/browse/sample > > but for example... from a draw full of cutlery you don't "take an > > example spoon", you "take a sample spoon". > > > > > > So it depends on where you want the focus to be. > > * If the focus is on working with a sample object, then <sample> makes > > a better pragma for the method creating it. > > * If the focus is on the code producing the sample, then <example> is > > a better choice. > > > > Maybe you are constrained by existing industry terminology, > > but "Example-Driven Development" might be equally called > > "Sample-Driven Development". > > Without having read into the topic, intuitively the former broadly > > encompasses copying static code > > while the latter feels more limited to working with an object. > > > > > > My proposal... > > * <sample> provides a narrower sense of side-effect-free provision of > > object to work with. "Samples are often tangible parts and can be > > observed" > > * <example> provides a broader sense of showing how things work > > together, in ways that may or may-not include side effects that you > > don't actually want to execute - just to refer to. "Examples are used > > [to] illustrate something. [Its] expected that the example will be > > imitated and replicated among its audience." > > * <script> provides a sense of system management, of methods causing > > significant side effects. You won't want to copy these methods, just > > make use them. > > > > <sampleScript> feels awkward to apply to examples, since by my these > > are neither samples nor scripts. > > > > > > cheers -ben > > > > > >> Executing this method as an example should have no side-effects (either because the method itself does not have a side-effect, or because the example method defines how the cleanup should happen using the mechanism provided by GTExamples). > >> > >> This meaning is different from the meaning of the <example> pragma used through Pharo. There are currently 55 places that use this pragma inside Pharo and most of them come from FastTable. As things will progress and more libraries might use GTExamples, the situation can become confusing. > >> > >> To make things less confusing in the future, I would like to define the meaning of the <example> to denote a method that returns an object without having side effects. Would you agree with this? > >> > >> If yes, I would suggest the name of the new pragma that would replace the existing one to include “script” in the name. For example, <sampleScript>. > >> > >> What do you think? > >> > >> Cheers, > >> Doru > >> > >> > >> -- > >> www.tudorgirba.com > >> www.feenk.com > >> > >> "Reasonable is what we are accustomed with." > > -- > www.tudorgirba.com > www.feenk.com > > “Software has no shape. Actually, it has no one shape. It has many." > > > -- www.tudorgirba.com www.feenk.com "Next time you see your life passing by, say 'hi' and get to know her." |
Re: a request to change the meaning of <example> pragma
|
|
In reply to this post by Tudor Girba-2
Ok, thx. Will try. I am tired of examples in comments, selecting stuff etc when it is possible to have a click on an icon. Thx for this thing. Phil On Mon, Dec 19, 2016 at 8:34 AM, Tudor Girba <[hidden email]> wrote: We did not try, but it should not be a problem, except for the fact that there will be a GTExample class in Pharo 5 packaged with GTInspector. |
Re: a request to change the meaning of <example> pragma
|
|
Hi Phil,
it is already (since a long time) possible to mark a method with <example> including
the icon clickable thing.
But now (and already a year ago) Tudor wants to change semantics - as such marked methods always have to return a single sample instance of the class instead of being what they are now: just a little
bit of code examples that can do anything and return anything.
I would vote for a different pragma for his approach like <sample> or <exemplar> better justifiying what the method does: returning a sample instance.
Thanks
Torsten Gesendet: Montag, 19. Dezember 2016 um 10:24 Uhr
Von: "[hidden email]" <[hidden email]> An: "Pharo Development List" <[hidden email]> Betreff: Re: [Pharo-dev] a request to change the meaning of <example> pragma Ok, thx. Will try.
I am tired of examples in comments, selecting stuff etc when it is possible to have a click on an icon.
Thx for this thing.
Phil
On Mon, Dec 19, 2016 at 8:34 AM, Tudor Girba <[hidden email]> wrote:
We did not try, but it should not be a problem, except for the fact that there will be a GTExample class in Pharo 5 packaged with GTInspector. |
Re: a request to change the meaning of <example> pragma
|
|
In reply to this post by Tudor Girba-2
Hi Tudor,
we all already had exchanged on this topic in discussions on this list back a year ago or even before and as we have seen there were different arguments and different point of views. Actions to make Pharo more known are always appreciated and as you made more progress on the idea/tools side for sure you can demonstrate better what can be done with this approach. But does it mean all the other arguments are now invalid because of this? I don't think so. Anything described/demonstrated in this approach can perfectly be done without changing the meaning of the "example" pragma and by using an own pragma to mark methods following that idea. Trying to hijack "example" pragma again as it is your preferred pragma name does not help because this is like enforcing your own point of view on the topic to people like me following the existing "example" usage. Currently <example> and its usage is very generous and not so restrictive what kind of example the method contains or what return value it may provide. Also counting the current usage in the default image does not tell you anything as it leaves out all external projects. Similar to Ben I personally have not changed my point of view. I agree with him in using an own and more specific pragma like - <sample> - <sampleInstance> - <exemplar> better depicting the meaning of returning an sample/sample instance/exemplar of an instance of the class. I would be fine with using just "sample" as well as "Sample driven development". There is no need to change the meaning of the existing pragma <example> which is more general and can be any kind of example like: - example of usage - a simple example script - sample instance - example of an algorithm - example on how to use several classes together - ... For <example> it is not necessary to return exactly once instance of the class where the pragma is used in. Thx T. |
Re: a request to change the meaning of <example> pragma
|
|
In reply to this post by Tudor Girba-2
Hi all In nautilus in Pharo 60 when you use <sampleInstance> you can get an inspector on the object returned by the method Example Die class >> d6 <sampleInstance> ^ self faces: 6 I started to use this pragma in all my libraries and I chose it to avoid conflict with <example> and others. I can change another time to make everybody happy. But I would like to avoid to have to change everything again because this is the second time. :) So let me know. Now as I already said in the past, I will veto the integration of Examples based on pragmas to compose them. I do not want to need a special tools to get example working. But you know all that. Stef On Sun, Dec 18, 2016 at 10:49 PM, Tudor Girba <[hidden email]> wrote: Hi, |
Re: a request to change the meaning of <example> pragma
|
|
In reply to this post by Torsten Bergmann
Hi,
Thanks for reacting. Knowing that you were a strong debate counterpart, I would be very happy to work with you on this topic :). As Nicolai noticed, GTExamples is significantly more than sample instances. For example, right now, it is the basis for building examples that are also tests. Furthermore, we played also with building documentation around it. Sample instances are just the prerequisite for making this happen, but the method is very much an example. I do not want to hijack anything. The result of the debate a year ago was to not introduce the <example> pragma at all to have the chance of comparing solutions rather than just having something that is half backed and get stuck with it. Now we have 55 such <example> methods in the image. GTExamples will not change because we do not learn from samples or exemplars, we learn from examples, and the goal of this project is to offer a solution for live documentation and testing. You might not believe in it, and that is fine. We wrote down the documentation so that people can look at it. People do not, and that is fine as well. Examples is a very rich word, and it would be a pity to not spend it to its full potential. I am not saying that the current form of GTExamples is that full potential, but I do want us to dream for more than what is achievable easily. I already said that one issue we have with GTExamples is that the composition based on pragmas can become somewhat difficult (at least with the current tools) and we are looking for alternatives. Even so, this library is already in use and it will be used further. Furthermore, not using the term “examples" for this goal is a bit like saying that because some methods used to be called “tests” before SUnit appeared that SUnit should have employed a different term than tests to denote the methods. For example, they could have been called assertions. Cheers, Doru > On Dec 19, 2016, at 1:03 PM, Torsten Bergmann <[hidden email]> wrote: > > Hi Tudor, > > we all already had exchanged on this topic in discussions on this list back a year ago or even before > and as we have seen there were different arguments and different point of views. > > Actions to make Pharo more known are always appreciated and as you made more progress on the idea/tools > side for sure you can demonstrate better what can be done with this approach. > > But does it mean all the other arguments are now invalid because of this? I don't think so. > > Anything described/demonstrated in this approach can perfectly be done without changing the meaning > of the "example" pragma and by using an own pragma to mark methods following that idea. > > Trying to hijack "example" pragma again as it is your preferred pragma name does not help because this is > like enforcing your own point of view on the topic to people like me following the existing > "example" usage. Currently <example> and its usage is very generous and not so restrictive what kind of > example the method contains or what return value it may provide. > > Also counting the current usage in the default image does not tell you anything as it leaves out all external > projects. > > > Similar to Ben I personally have not changed my point of view. I agree with him in using an own and more specific > pragma like > > - <sample> > - <sampleInstance> > - <exemplar> > > better depicting the meaning of returning an sample/sample instance/exemplar of an instance of the class. > I would be fine with using just "sample" as well as "Sample driven development". > > > There is no need to change the meaning of the existing pragma <example> which is more > general and can be any kind of example like: > - example of usage > - a simple example script > - sample instance > - example of an algorithm > - example on how to use several classes together > - ... > > For <example> it is not necessary to return exactly once instance of the class where the pragma > is used in. > > Thx > T. > -- www.tudorgirba.com www.feenk.com "Innovation comes in the least expected form. That is, if it is expected, it already happened." |
Re: a request to change the meaning of <example> pragma
|
|
In reply to this post by Stephane Ducasse-3
Hi,
Thanks for the message. There are several points under discussion. I am not arguing now for introduction of GTExamples in the Pharo distribution. This is a discussion for the future. But, I would like to distinguish between the current implementation and the goal. I believe "Example-driven development" is an interesting possibility to raise awareness for Pharo especially if we double the technology with a practice or method that will be in line with the idea of live programming. It might sound far fetched, but I really believe we can deliver on that. GTExamples is a full first version (not a prototype). It certainly will not be the last. Regarding composition, in its simplest form, there is no composition, and for that you only need unary methods with <gtExample>. But, you do get the possibility of adding assertions and of specifying cleanups. So, relying on plain <gtExample> does not force you to use dependencies but you get extra advantages. Nevertheless, as I said before, composition is a point on which we want to work more. I believe it should be possible to use static analysis to recover example dependencies without the need of injecting arguments based on pragmas, but it is not yet clear how this would work. Cheers, Doru > On Dec 19, 2016, at 1:32 PM, Stephane Ducasse <[hidden email]> wrote: > > Hi all > > In nautilus in Pharo 60 when you use > <sampleInstance> you can get an inspector on the object returned by the method > > Example > > Die class >> d6 > <sampleInstance> > ^ self faces: 6 > > I started to use this pragma in all my libraries and I chose it to avoid conflict with <example> and others. > > I can change another time to make everybody happy. But I would like to avoid to have to change everything again because this is the second time. :) > So let me know. > > Now as I already said in the past, I will veto the integration of Examples based on pragmas to compose them. > I do not want to need a special tools to get example working. But you know all that. > > > Stef > > > > > > > > > > On Sun, Dec 18, 2016 at 10:49 PM, Tudor Girba <[hidden email]> wrote: > Hi, > > As you might know, a while ago we created GTExamples, a framework that supports both example-based live documentation and testing: > http://gtoolkit.org/doc/Examples/examples.html > > GTExamples was part of the GTInspector for a while, but as it evolved, we pulled it out in a separate project. This separate project is not in Pharo anymore but it is part of the full GToolkit configuration (Pharo only ships the core of GToolkit). The idea of taking GTExamples out was to allow the community to have a more elaborate discussion about the role of examples in our environment. > > I have invited you to join that conversation, but it did not take off. I understand that perhaps the topic does not look appealing at this moment. > > We will certainly continue to evolve GTExamples both on the semantics level of the dependency constructs and on the integration with tools. Our goal is to enable a new practice that I would like to call Example-Guilded Development (or Example-Driven Development), and position Pharo to be the only platform on which someone can do that. But, that is our goal, and does not have to be the same with other people’s goal. > > Right now, GTExamples relies on the <gtExample> pragma to denote a method that returns an object that exemplifies something. Executing this method as an example should have no side-effects (either because the method itself does not have a side-effect, or because the example method defines how the cleanup should happen using the mechanism provided by GTExamples). > > This meaning is different from the meaning of the <example> pragma used through Pharo. There are currently 55 places that use this pragma inside Pharo and most of them come from FastTable. As things will progress and more libraries might use GTExamples, the situation can become confusing. > > To make things less confusing in the future, I would like to define the meaning of the <example> to denote a method that returns an object without having side effects. Would you agree with this? > > If yes, I would suggest the name of the new pragma that would replace the existing one to include “script” in the name. For example, <sampleScript>. > > What do you think? > > Cheers, > Doru > > > -- > www.tudorgirba.com > www.feenk.com > > "Reasonable is what we are accustomed with." > > > -- www.tudorgirba.com www.feenk.com "Problem solving efficiency grows with the abstractness level of problem understanding." |
|
|
In reply to this post by Nicolai Hess-3-2
On Mon, Dec 19, 2016 at 3:53 PM, Nicolai Hess <[hidden email]> wrote:
> > > 2016-12-19 8:46 GMT+01:00 Tudor Girba <[hidden email]>: >> >> Hi, >> >> I would prefer if this thread does not transform in a terminology debate >> too much. >> > > @Doru, but you asked "What do you think" and I think Bens response about > sampleScript is valid > > @Ben Did you check Dorus blog entry > (http://gtoolkit.org/doc/Examples/examples.html) I think this makes > it more clear why gttExamples are more than just methods producsing > "samples" I hadn't seen that before. Thanks for the tip. So I cede the point the aim is something more than just a sample. cheers -ben > > >> >> Example is a term that fits both the code and the returning object. >> <gtExample> is applied on a method and it primarily describes that method. >> The term “example” also describes the meta object that is wraps the concrete >> return value with the information from the method (for example, the label of >> the example, the link to the subject, or the dependencies to other >> examples). The example term is also important from the metaphor point of >> view: "we learn from examples”. >> >> Cheers, >> Doru >> >> >> >> > On Dec 19, 2016, at 3:34 AM, Ben Coman <[hidden email]> wrote: >> > >> > On Mon, Dec 19, 2016 at 5:49 AM, Tudor Girba <[hidden email]> >> > wrote: >> >> Hi, >> >> >> >> As you might know, a while ago we created GTExamples, a framework that >> >> supports both example-based live documentation and testing: >> >> http://gtoolkit.org/doc/Examples/examples.html >> >> >> >> GTExamples was part of the GTInspector for a while, but as it evolved, >> >> we pulled it out in a separate project. This separate project is not in >> >> Pharo anymore but it is part of the full GToolkit configuration (Pharo only >> >> ships the core of GToolkit). The idea of taking GTExamples out was to allow >> >> the community to have a more elaborate discussion about the role of examples >> >> in our environment. >> >> >> >> I have invited you to join that conversation, but it did not take off. >> >> I understand that perhaps the topic does not look appealing at this moment. >> >> >> >> We will certainly continue to evolve GTExamples both on the semantics >> >> level of the dependency constructs and on the integration with tools. Our >> >> goal is to enable a new practice that I would like to call Example-Guilded >> >> Development (or Example-Driven Development), and position Pharo to be the >> >> only platform on which someone can do that. But, that is our goal, and does >> >> not have to be the same with other people’s goal. >> >> >> >> Right now, GTExamples relies on the <gtExample> pragma to denote a >> >> method that returns an object that exemplifies something. >> > >> > >> > I've previously not done a good job of promoting the use of <sample> >> > for this. I'll try spinning this wheel once more. >> > >> > There are two concepts to consider: >> > * The returned object. >> > * The method code that creates the returned object. >> > >> > The "returned object" is best considered a <sample>. >> > The "method code" is best considered an <example> that produces the >> > sample. >> > >> > http://www.differencebetween.com/difference-between-example-and-vs-sample/ >> > >> > The term "exemplifies/exemplification" associates equally with both... >> > * http://www.thesaurus.com/browse/example >> > * http://www.thesaurus.com/browse/sample >> > but for example... from a draw full of cutlery you don't "take an >> > example spoon", you "take a sample spoon". >> > >> > >> > So it depends on where you want the focus to be. >> > * If the focus is on working with a sample object, then <sample> makes >> > a better pragma for the method creating it. >> > * If the focus is on the code producing the sample, then <example> is >> > a better choice. >> > >> > Maybe you are constrained by existing industry terminology, >> > but "Example-Driven Development" might be equally called >> > "Sample-Driven Development". >> > Without having read into the topic, intuitively the former broadly >> > encompasses copying static code >> > while the latter feels more limited to working with an object. >> > >> > >> > My proposal... >> > * <sample> provides a narrower sense of side-effect-free provision of >> > object to work with. "Samples are often tangible parts and can be >> > observed" >> > * <example> provides a broader sense of showing how things work >> > together, in ways that may or may-not include side effects that you >> > don't actually want to execute - just to refer to. "Examples are used >> > [to] illustrate something. [Its] expected that the example will be >> > imitated and replicated among its audience." >> > * <script> provides a sense of system management, of methods causing >> > significant side effects. You won't want to copy these methods, just >> > make use them. >> > >> > <sampleScript> feels awkward to apply to examples, since by my these >> > are neither samples nor scripts. >> > >> > >> > cheers -ben >> > >> > >> >> Executing this method as an example should have no side-effects (either >> >> because the method itself does not have a side-effect, or because the >> >> example method defines how the cleanup should happen using the mechanism >> >> provided by GTExamples). >> >> >> >> This meaning is different from the meaning of the <example> pragma used >> >> through Pharo. There are currently 55 places that use this pragma inside >> >> Pharo and most of them come from FastTable. As things will progress and more >> >> libraries might use GTExamples, the situation can become confusing. >> >> >> >> To make things less confusing in the future, I would like to define the >> >> meaning of the <example> to denote a method that returns an object without >> >> having side effects. Would you agree with this? >> >> >> >> If yes, I would suggest the name of the new pragma that would replace >> >> the existing one to include “script” in the name. For example, >> >> <sampleScript>. >> >> >> >> What do you think? >> >> >> >> Cheers, >> >> Doru >> >> >> >> >> >> -- >> >> www.tudorgirba.com >> >> www.feenk.com >> >> >> >> "Reasonable is what we are accustomed with." >> >> -- >> www.tudorgirba.com >> www.feenk.com >> >> “Software has no shape. Actually, it has no one shape. It has many." >> >> > |
Re: a request to change the meaning of <example> pragma
|
|
Hi,
> On Dec 19, 2016, at 5:49 PM, Ben Coman <[hidden email]> wrote: > > On Mon, Dec 19, 2016 at 3:53 PM, Nicolai Hess <[hidden email]> wrote: >> >> >> 2016-12-19 8:46 GMT+01:00 Tudor Girba <[hidden email]>: >>> >>> Hi, >>> >>> I would prefer if this thread does not transform in a terminology debate >>> too much. >>> >> >> @Doru, but you asked "What do you think" and I think Bens response about >> sampleScript is valid >> >> @Ben Did you check Dorus blog entry >> (http://gtoolkit.org/doc/Examples/examples.html) I think this makes >> it more clear why gttExamples are more than just methods producsing >> "samples" > > > I hadn't seen that before. Thanks for the tip. > So I cede the point the aim is something more than just a sample. Thank you! But, if we are at it, please let’s continue and brainstorm. The existing implementation should be taken as a first fully working version. It would be great to have people play with it and find its weaknesses. Cheers, Doru > cheers -ben > >> >> >>> >>> Example is a term that fits both the code and the returning object. >>> <gtExample> is applied on a method and it primarily describes that method. >>> The term “example” also describes the meta object that is wraps the concrete >>> return value with the information from the method (for example, the label of >>> the example, the link to the subject, or the dependencies to other >>> examples). The example term is also important from the metaphor point of >>> view: "we learn from examples”. >>> >>> Cheers, >>> Doru >>> >>> >>> >>>> On Dec 19, 2016, at 3:34 AM, Ben Coman <[hidden email]> wrote: >>>> >>>> On Mon, Dec 19, 2016 at 5:49 AM, Tudor Girba <[hidden email]> >>>> wrote: >>>>> Hi, >>>>> >>>>> As you might know, a while ago we created GTExamples, a framework that >>>>> supports both example-based live documentation and testing: >>>>> http://gtoolkit.org/doc/Examples/examples.html >>>>> >>>>> GTExamples was part of the GTInspector for a while, but as it evolved, >>>>> we pulled it out in a separate project. This separate project is not in >>>>> Pharo anymore but it is part of the full GToolkit configuration (Pharo only >>>>> ships the core of GToolkit). The idea of taking GTExamples out was to allow >>>>> the community to have a more elaborate discussion about the role of examples >>>>> in our environment. >>>>> >>>>> I have invited you to join that conversation, but it did not take off. >>>>> I understand that perhaps the topic does not look appealing at this moment. >>>>> >>>>> We will certainly continue to evolve GTExamples both on the semantics >>>>> level of the dependency constructs and on the integration with tools. Our >>>>> goal is to enable a new practice that I would like to call Example-Guilded >>>>> Development (or Example-Driven Development), and position Pharo to be the >>>>> only platform on which someone can do that. But, that is our goal, and does >>>>> not have to be the same with other people’s goal. >>>>> >>>>> Right now, GTExamples relies on the <gtExample> pragma to denote a >>>>> method that returns an object that exemplifies something. >>>> >>>> >>>> I've previously not done a good job of promoting the use of <sample> >>>> for this. I'll try spinning this wheel once more. >>>> >>>> There are two concepts to consider: >>>> * The returned object. >>>> * The method code that creates the returned object. >>>> >>>> The "returned object" is best considered a <sample>. >>>> The "method code" is best considered an <example> that produces the >>>> sample. >>>> >>>> http://www.differencebetween.com/difference-between-example-and-vs-sample/ >>>> >>>> The term "exemplifies/exemplification" associates equally with both... >>>> * http://www.thesaurus.com/browse/example >>>> * http://www.thesaurus.com/browse/sample >>>> but for example... from a draw full of cutlery you don't "take an >>>> example spoon", you "take a sample spoon". >>>> >>>> >>>> So it depends on where you want the focus to be. >>>> * If the focus is on working with a sample object, then <sample> makes >>>> a better pragma for the method creating it. >>>> * If the focus is on the code producing the sample, then <example> is >>>> a better choice. >>>> >>>> Maybe you are constrained by existing industry terminology, >>>> but "Example-Driven Development" might be equally called >>>> "Sample-Driven Development". >>>> Without having read into the topic, intuitively the former broadly >>>> encompasses copying static code >>>> while the latter feels more limited to working with an object. >>>> >>>> >>>> My proposal... >>>> * <sample> provides a narrower sense of side-effect-free provision of >>>> object to work with. "Samples are often tangible parts and can be >>>> observed" >>>> * <example> provides a broader sense of showing how things work >>>> together, in ways that may or may-not include side effects that you >>>> don't actually want to execute - just to refer to. "Examples are used >>>> [to] illustrate something. [Its] expected that the example will be >>>> imitated and replicated among its audience." >>>> * <script> provides a sense of system management, of methods causing >>>> significant side effects. You won't want to copy these methods, just >>>> make use them. >>>> >>>> <sampleScript> feels awkward to apply to examples, since by my these >>>> are neither samples nor scripts. >>>> >>>> >>>> cheers -ben >>>> >>>> >>>>> Executing this method as an example should have no side-effects (either >>>>> because the method itself does not have a side-effect, or because the >>>>> example method defines how the cleanup should happen using the mechanism >>>>> provided by GTExamples). >>>>> >>>>> This meaning is different from the meaning of the <example> pragma used >>>>> through Pharo. There are currently 55 places that use this pragma inside >>>>> Pharo and most of them come from FastTable. As things will progress and more >>>>> libraries might use GTExamples, the situation can become confusing. >>>>> >>>>> To make things less confusing in the future, I would like to define the >>>>> meaning of the <example> to denote a method that returns an object without >>>>> having side effects. Would you agree with this? >>>>> >>>>> If yes, I would suggest the name of the new pragma that would replace >>>>> the existing one to include “script” in the name. For example, >>>>> <sampleScript>. >>>>> >>>>> What do you think? >>>>> >>>>> Cheers, >>>>> Doru >>>>> >>>>> >>>>> -- >>>>> www.tudorgirba.com >>>>> www.feenk.com >>>>> >>>>> "Reasonable is what we are accustomed with." >>> >>> -- >>> www.tudorgirba.com >>> www.feenk.com >>> >>> “Software has no shape. Actually, it has no one shape. It has many." -- www.tudorgirba.com www.feenk.com "If you can't say why something is relevant, it probably isn't." |
Re: a request to change the meaning of <example> pragma
|
|
personally I like what I see, I don't have any objection. My personal opinion on this is that Pharo needs a proper documentation system which what examples are part of like Java or Python doc strings. But then a doc strings system is far more complex than the GTExample and a lot more work. In the mean time GTExample looks like a good enhancement to have. I also dont see it creating any incompatibilities with the existing <example> pragma. On Mon, Dec 19, 2016 at 7:27 PM Tudor Girba <[hidden email]> wrote: Hi, |
|
|
In reply to this post by Torsten Bergmann
+1
Graham Torsten Bergmann wrote: > Hi Tudor, > > we all already had exchanged on this topic in discussions on this list back a year ago or even before > and as we have seen there were different arguments and different point of views. > > Actions to make Pharo more known are always appreciated and as you made more progress on the idea/tools > side for sure you can demonstrate better what can be done with this approach. > > But does it mean all the other arguments are now invalid because of this? I don't think so. > > Anything described/demonstrated in this approach can perfectly be done without changing the meaning > of the "example" pragma and by using an own pragma to mark methods following that idea. > > Trying to hijack "example" pragma again as it is your preferred pragma name does not help because this is > like enforcing your own point of view on the topic to people like me following the existing > "example" usage. Currently<example> and its usage is very generous and not so restrictive what kind of > example the method contains or what return value it may provide. > > Also counting the current usage in the default image does not tell you anything as it leaves out all external > projects. > > > Similar to Ben I personally have not changed my point of view. I agree with him in using an own and more specific > pragma like > > -<sample> > -<sampleInstance> > -<exemplar> > > better depicting the meaning of returning an sample/sample instance/exemplar of an instance of the class. > I would be fine with using just "sample" as well as "Sample driven development". > > > There is no need to change the meaning of the existing pragma<example> which is more > general and can be any kind of example like: > - example of usage > - a simple example script > - sample instance > - example of an algorithm > - example on how to use several classes together > - ... > > For<example> it is not necessary to return exactly once instance of the class where the pragma > is used in. > > Thx > T. > >
Graham McLeod
graham@inspired.org www.inspired.org |
graham.vcf (484 bytes)
Re: a request to change the meaning of <example> pragma
|
Administrator
|
In reply to this post by Stephane Ducasse-3
Cool! Great feature :)
Cheers,
Sean |
«
Return to Pharo Smalltalk Developers
|
1 view|%1 views
| Free forum by Nabble | Edit this page |