Hi, > On Dec 19, 2016, at 5:49 PM, Ben Coman <[email protected]> wrote: > > On Mon, Dec 19, 2016 at 3:53 PM, Nicolai Hess <[email protected]> wrote: >> >> >> 2016-12-19 8:46 GMT+01:00 Tudor Girba <[email protected]>: >>> >>> 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 <[email protected]> wrote: >>>> >>>> On Mon, Dec 19, 2016 at 5:49 AM, Tudor Girba <[email protected]> >>>> 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."
