On Mon, Dec 19, 2016 at 3:53 PM, Nicolai Hess <nicolaih...@gmail.com> wrote: > > > 2016-12-19 8:46 GMT+01:00 Tudor Girba <tu...@tudorgirba.com>: >> >> 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 <b...@openinworld.com> wrote: >> > >> > On Mon, Dec 19, 2016 at 5:49 AM, Tudor Girba <tu...@tudorgirba.com> >> > 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." >> >> >
