Hi, > On Dec 19, 2016, at 8:53 AM, 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
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 <[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 "Next time you see your life passing by, say 'hi' and get to know her."
