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" > 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." > > >
