On Mon, Jun 22, 2015 at 11:17 PM, Torsten Bergmann <asta...@gmx.de> wrote: > Hi Peter, > > there was no agreement - so we rolled back for Pharo 4 to discuss/decide for > Pharo 5. > > I communicated already how I would solve it to get IMHO a consistent and > easy understandable solution: > > 1. executable example > ===================== > We talk about executable code here: an "example" in the traditional > Smalltalk sense > means ONLY a runnable piece of code to demonstrate something. Since a long > time and not only in Pharo this > is typically done in methods with prefix "example". It is important to note > that these methods COULD BUT > MUST NOT RETURN an instance. Usually such a method is only there to > demonstrate code. > > These methods with the "example" in the name are currently honored by > Nautilus with the > clickable icon. See SystemProgressMorph>>exampleChangeLabel or others. > > => To not be limited to the prefix in the method name I proposed to be able > to additionally use the <example> pragma to mark example methods. > This way you can choose the method name freely to give an example to > others > on how to use them. > > 2. returning examples > ===================== > While some example methods just demo code and code usage (like "Job > example" or "BorderedMorph exampleGradient") > a subset of them directly return an instance of the method defining class > (like LabelMorph>>example). > > The idea of the GT Tools is to call these methods and display the return > value as inspectable "instances" in the tools, > so for instance if you inspect class VirtualMachine or Character you get a > tab entitled "E.g." where you can click on > these sample instances. > > GT and (because GT )now latest Pharo currently still uses "gtExample" > method prefix or <gtExample> pragma to mark such methods and there > is also to wish to remove the "gt" prefix. But with this we would have a > clash with the other "exampleXXX" usage. > > => I would propose to mark the code examples that return an instance with > an <exemplar> method. > > According to Google definition of <exemplar> noun - "a person or thing > serving as a typical example or excellent model." > Urban dictionary defines <exemplar> as "a typical or standard model or > specimen" > > So I proposed and still propose > - "exampleXXX" prefixed methods and <example> pragma for traditional > examples as used in other Smalltalks and Pharo before > - "exemplarXXX" prefixed methods and <exemplar> pragma (mark code that > return an instance always) for the future inspection > of exemplars in the tools
Sorry. I'm going to have to play the native english speaker card here. I could live with it, but "examplar" just doesn't sound right for this. * Dictionary meanings are useful, but meaning can be skewed without contemporary context. * Dictionaries cover a lot of corner cases, some inherited from a hundred years ago, and language evolves. They may remain technically correct and understandable, but not sound "right". * I've probably only seen the word used couple of times in my life, never in this context. * I notice its also a German word. I expect its hard to disassociate from its common German usage. Sorry, after English stole it from German, it probably corrupted it. * Check its synonyms: "epitome, perfect example, shining example, model, paragon, ideal...". This is its contemporary meaning and I guess the returned sample won't be expected to be the "best most perfect sample". It will just be "some sample" or a "basic sample" for you to inspect. * "Sample" is 2 characters shorter than "Exemplar" to fit in label of the GT tab. I presume its useful to match the tab label with the pragma. cheers -ben
