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