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 <[email protected]> wrote: > 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." > > >
