- Pharo-users - lists.pharo.org

Re: [Pharo-users] About patterns, UML and documentation

by Peter Uhnak

> > with the tool and layout and stuff rather than concentrate on what is Well there are tools such as PlantUML that generate it for you, you can provide some hints, but generally it tends to be good enough to not be worried about layout. I have a Pharo -> PlantUML generator for class, object, and sequence diagrams somewhere, as I've used it to gain insight about some subsystems on several occasions, but I never published it... it's a bit of hacky code around Pharo's metaprogramming and reflecting capabilities... so you could in principle write it by hand in an hour or so... in fact doing so by hand might be beneficial for specific problem, because you can reverse-engineer only the parts that you care about instead of having everything or having a complex generator parametrization... > > Take Sven's NeoCSV package as an example. Great documentation and very > > good method names. and a complete set of tests. > > > > Sounds frightening at first if you come from a static typing background, > > but in my experience it works quite well. I don't think that this is a good example. From user perspective you usually interact with only two classes (reader and writer)... and I don't really see how UML could help you there. The internal architecture on the other hand, or tools with models could benefit from it much more (at least in class diagrams, the relationships between elements tends to be the most important part, so if you have one or two classes... then you won't have much connections...). Peter On Thu, Jun 08, 2017 at 08:40:34AM +0200, Marc Hanisch via Pharo-users wrote: > Date: Thu, 8 Jun 2017 08:40:34 +0200 > From: Marc Hanisch <marc.hanisch(a)googlemail.com> > To: Any question about pharo is welcome <pharo-users(a)lists.pharo.org> > Subject: Re: [Pharo-users] About patterns, UML and documentation > > Thanks Todd and Joachim for your fast responses, > > your examples are very interesting! I think I got the point! ...And you are > so true about your experience with UML and the struggle to group / align > all graphical objects so it is still understandable ;-) > > Best regards, > Marc > > 2017-06-08 7:53 GMT+02:00 jtuchel(a)objektfabrik.de <jtuchel(a)objektfabrik.de>: > > > I think the key to this is intention revealing names and comments. And > > shipping unit tests that are the best example of "running documentation". > > > > Take Sven's NeoCSV package as an example. Great documentation and very > > good method names. and a complete set of tests. > > > > Sounds frightening at first if you come from a static typing background, > > but in my experience it works quite well. > > > > There are UML tools. Some even allow round-trips where the UML diagrams > > can be generated from code (e.g. IBM/Instantiations have the UML Designer > > add-on), but to be honest, these only put you in high danger of playing > > with the tool and layout and stuff rather than concentrate on what is > > important. UML is fine for communicating the raw structure and basic ideas. > > Generating UML from code on the fly can help understand code, but I've seen > > too many projects that made the UML design documents an art of itself, and > > most of the times the diagrams were out of sync anyways... > > > > Just my 2 cents, > > > > Joachim > > > > > > -- > > ----------------------------------------------------------------------- > > Objektfabrik Joachim Tuchel mailto:jtuchel@objektfabrik.de > > Fliederweg 1 http://www.objektfabrik.de > > D-71640 Ludwigsburg http://joachimtuchel.wordpress.com > > Telefon: +49 7141 56 10 86 0 Fax: +49 7141 56 10 86 1 > > > > > >

June 8, 2017

Re: [Pharo-users] About patterns, UML and documentation

by Marc Hanisch

Thanks Todd and Joachim for your fast responses, your examples are very interesting! I think I got the point! ...And you are so true about your experience with UML and the struggle to group / align all graphical objects so it is still understandable ;-) Best regards, Marc 2017-06-08 7:53 GMT+02:00 jtuchel(a)objektfabrik.de <jtuchel(a)objektfabrik.de>: > I think the key to this is intention revealing names and comments. And > shipping unit tests that are the best example of "running documentation". > > Take Sven's NeoCSV package as an example. Great documentation and very > good method names. and a complete set of tests. > > Sounds frightening at first if you come from a static typing background, > but in my experience it works quite well. > > There are UML tools. Some even allow round-trips where the UML diagrams > can be generated from code (e.g. IBM/Instantiations have the UML Designer > add-on), but to be honest, these only put you in high danger of playing > with the tool and layout and stuff rather than concentrate on what is > important. UML is fine for communicating the raw structure and basic ideas. > Generating UML from code on the fly can help understand code, but I've seen > too many projects that made the UML design documents an art of itself, and > most of the times the diagrams were out of sync anyways... > > Just my 2 cents, > > Joachim > > > -- > ----------------------------------------------------------------------- > Objektfabrik Joachim Tuchel mailto:jtuchel@objektfabrik.de > Fliederweg 1 http://www.objektfabrik.de > D-71640 Ludwigsburg http://joachimtuchel.wordpress.com > Telefon: +49 7141 56 10 86 0 Fax: +49 7141 56 10 86 1 > > >

June 8, 2017

Re: [Pharo-users] About patterns, UML and documentation

by jtuchel＠objektfabrik.de

I think the key to this is intention revealing names and comments. And shipping unit tests that are the best example of "running documentation". Take Sven's NeoCSV package as an example. Great documentation and very good method names. and a complete set of tests. Sounds frightening at first if you come from a static typing background, but in my experience it works quite well. There are UML tools. Some even allow round-trips where the UML diagrams can be generated from code (e.g. IBM/Instantiations have the UML Designer add-on), but to be honest, these only put you in high danger of playing with the tool and layout and stuff rather than concentrate on what is important. UML is fine for communicating the raw structure and basic ideas. Generating UML from code on the fly can help understand code, but I've seen too many projects that made the UML design documents an art of itself, and most of the times the diagrams were out of sync anyways... Just my 2 cents, Joachim -- ----------------------------------------------------------------------- Objektfabrik Joachim Tuchel mailto:jtuchel@objektfabrik.de Fliederweg 1 http://www.objektfabrik.de D-71640 Ludwigsburg http://joachimtuchel.wordpress.com Telefon: +49 7141 56 10 86 0 Fax: +49 7141 56 10 86 1

June 8, 2017

Re: [Pharo-users] About patterns, UML and documentation

by Todd Blanchard

Hi Marc. In Smalltalk, we rely on naming conventions a lot. The great thing is that Smalltalk selectors/symbols/method names read like English. aDictionary at: aKey put: anObject. aString indexOf: aCharacter startingAt: start ifAbsent: aBlock Seems pretty clear, no? We also rely on comments. For instance this is the class comment for IceRepository - an abstraction of a git repo. I represent an interface to a git repository. My main responsibilities are: - Load/update both baselines and individual packages from the repository. - Commit changes to the local repository and publish them to a remote repository. - Browse other versions of the loaded packages. - Handle branches For the Collaborators Part: State my main collaborators and one line about how I interact with them. Public API and Key Messages - loadPackage: packageName - createBranch: newBranchName Sample usage: Git new origin: 'git@github.com:npasserini/pharo-git-test.git'. git loadPackage: 'Pharo-Git-Test'. Instance Variables - origin: A string representing the url of a remote git repository (used as origin) - repository: An IceGitTreeGitRemoteRepository, which provides underlying git operations. - location: <FileReference> The directory of the local repository. - commitDictionary: <Dictionary of IceCommitInfo> Cached dictonary from commitId (hex string) to all commits in the current branch (in the local repo). - subdirectory: <String> The subdirectory of the local repository which is handled by the underlying GitFileTree - versionDescriptors: <List of GitFileTreePackageEntry> cached list of all package versions saved in the (currently selected branch) of the (local) repository. - announcer: <Announcer> - branch: <IceBranch> currently selected branch. - loadedCode: <IceLoadedCode> Contains information about the loaded code for each package in this repository. (TODO: maybe handle special cases about loading different versions loaded for different packages, see: https://github.com/npasserini/iceberg/issues/139) I hope this helps. -Todd Blanchard > On Jun 7, 2017, at 10:17 PM, Marc Hanisch via Pharo-users <pharo-users(a)lists.pharo.org> wrote: > > > From: Marc Hanisch <marc.hanisch(a)googlemail.com> > Subject: About patterns, UML and documentation > Date: June 7, 2017 at 10:17:11 PM PDT > To: Any question about pharo is welcome <pharo-users(a)lists.pharo.org> > > > Hello, > > I don't know Smalltalk well enough to give myself an answer about the following topic: > > When using design patterns, one benefit of writing interfaces and passing objects, that implement this interface, to methods is, that the reader instantly knows: okay, here the method A expects something that implements method B. > > Due to the nature of being a dynamically typed language, Smalltalk does not need interfaces. An exception object is thrown when a message is passed to an object that does not implement that method. But this message send could be deep inside the code. > > How do you show to the reader of your code your intention, that you are expecting, let's say for example, an iterator or an object that implements method X, Y and Z? > > Just with your method comments? Do you use UML? If so, how (without interfaces that point to the required methods)? > > Sorry, but I think my understanding of OOP is still to much influenced by C++ and Java based teachings... > > Thanks and best regards, > Marc > >

June 8, 2017

About patterns, UML and documentation

by Marc Hanisch

Hello, I don't know Smalltalk well enough to give myself an answer about the following topic: When using design patterns, one benefit of writing interfaces and passing objects, that implement this interface, to methods is, that the reader instantly knows: okay, here the method A expects something that implements method B. Due to the nature of being a dynamically typed language, Smalltalk does not need interfaces. An exception object is thrown when a message is passed to an object that does not implement that method. But this message send could be deep inside the code. How do you show to the reader of your code your intention, that you are expecting, let's say for example, an iterator or an object that implements method X, Y and Z? Just with your method comments? Do you use UML? If so, how (without interfaces that point to the required methods)? Sorry, but I think my understanding of OOP is still to much influenced by C++ and Java based teachings... Thanks and best regards, Marc

June 8, 2017

Re: [Pharo-users] Traits, method flatten

by Sean P. DeNigris

HilaireFernandes wrote > I made another attempt to > persist this time with filetree://. The net result is the same, the > Traits logic is lost in the classes using the Traits: all traits methods > are duplicated !! I just got burned by this in ##50768. Methods inherited from traits were saved as part of the package containing the extended class, as well as the package containing the Trait itself. Ugh. Was this ever fixed by Pharo 6? ----- Cheers, Sean -- View this message in context: http://forum.world.st/Traits-method-flatten-tp4941799p4950378.html Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.

June 8, 2017

Re: [Pharo-users] Wiring objects, IoC and Service Locator

by Ben Coman

On Tue, Jun 6, 2017 at 11:48 PM, Attila Magyar <m.magyar3(a)gmail.com> wrote: > I don't think using a DI container worth the effort. They add lots of > complexities and solve very little. For some reason DI containers became > very popular in the Java world, but if you take a look at other programming > communities you'll realize that many people are perfectly happy without > using these containers. Using DI and using a DI container is orthogonal. As > you also said you can just pass dependencies to objects to achieve loose > coupling. Yes, you have to do this manually but what's the big deal? We're > talking about code with cyclomatic complexity of 1. Calling a constructor > is > not a problem that need to be solved. Using an external XML configuration > to > describe object wiring is the worst idea ever. > > Here is an article about using plain old object composition to do DI > > http://blog.davidpeterson.co.uk/2011/01/object-oriented-example.html > > Some more thoughts about the problems associated with DI containers: > > http://www.natpryce.com/articles/000783.html I liked this... "the [Dependency Injection] pattern also used to be called "third-party binding" or "third-party connect": some third party is responsible for connecting an object satisfying the service requirements of a component" This makes the subject seem less esoteric. It reminds me of hearing that the first (secret) task when doing a PhD is to invent new terms for common ones, and base your writings on that. Perhaps its the same for consultants and framework developers. ;P Or maybe everything seems esoteric until you have experience with it and I've not done much with Java, certainly not big applications. Thx Peter for your example and how you prior experience compares to Pharo. cheers -ben > http://higherorderlogic.com/2011/07/is-dependency-injection-like-facebook > > > > -- > View this message in context: http://forum.world.st/Wiring-o > bjects-IoC-and-Service-Locator-tp4949280p4949720.html > Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com. > >

June 8, 2017

Re: [Pharo-users] Porting Transducers to Pharo

by Denis Kudriashov

2017-06-07 22:04 GMT+02:00 phil(a)highoctane.be <phil(a)highoctane.be>: > I read your note about DoubleAgents for the tests, well, yeah this one we > do not have. I read about it on the blog of its maker and it looked decent > indeed. > I think Mocketry can easily replace DoubleAgents but API is different and most tests will needed rewrites

June 7, 2017

Re: [Pharo-users] How to migrate an object to a subclass of its class but with new inst vars ?

by Denis Kudriashov

2017-06-07 22:30 GMT+02:00 Steven Costiou <steven.costiou(a)kloum.io>: > But would it not be faster to just change the class (which finally works > with a little tuning) ? In fact your solution with anonymous subclass is doing what I describe underhood.

June 7, 2017

Re: [Pharo-users] Wiring objects, IoC and Service Locator

by Peter Uhnak

> I don't see what is special about this. You can easily arrange instance > creation order with methods on the class-side of your domain classes. I will not use the term "class", but rather a "service" (service can be just a single class, but that is not always the case). The point of inversion of control is provide the class with what is needed instead of the class creating it on it's own. Sure, you can create class-side helper, however that is very limited, such as the examples/samples as you've demonstrated. To give you an example, imagine that you have a class PeopleService that manages database of people, so it needs a connection to the database. Implemented in a naive way the class would have hard-coded credentials to a MySQL database and it would execute raw SQL queries. This works for a single class, but it creates a mess and mingles concerns; so instead you inverse the control and you provide PeopleService with e.g. a Persistence instance, which is already connected to the database; note however that you cannot just create the Persistence on the class-side, because you wouldn't even know what to instantiate (as you could e.g. use DbPersistence, FilePersistence, ...). And this is just a basic example. Imagine that the PeopleService also needs other services for it's use, and those services need more services, and you want to keep everything separated as much as possible... instantiation by hand will simply not cut it So the service locator/DI configuration (whether as annotations or in a XML file) keeps the actual classes separated from concrete instances; the service depends on abstract interfaces, not specific classes; only the conf determines the specific ones, and more often than not there will be several different configurations _at the same time_. To continue with the example you could have one config production using e.g. OraclePersistence, another for development using MySQLPersistance, another for test server using MemoryPersistence, etc. (also with different credentials, and whatnot). Keep in mind however that relates primarily to using application frameworks, where the framework mandates the control, and the framework is the one calling you, and therefore it will also provide you with necessary parts. After all you are not even creating PeopleService class, the framework instantiates it for you and gives it to another services/classes that needed it. Now I don't feel like there are many application frameworks in Pharo, maybe Seaside has something of this sorts? I guess Spec can be a bit framework-y, as the basic spec widgets do not actually know what Morphic counterparts will be created for them, and Spec looks up the actual class in a hard-coded data table (which might as well be a XML file), but that comes closer to ServiceLocator than DI (as Spec widgets should not actually communicate down to morphic). I've used dependency injection for five years at my previous work and frankly I cannot imagine living without it there, but I've never felt the need for it in Pharo. This is probably more related to working in Pharo on completely different things and writing small libraries. However I wouldn't be surprised if the liveness of Smalltalk/Pharo environment eliminated some of the problems that DI is trying to solve. But then again, there are many ways to build systems, and not all need or benefit DI/IoC. Peter > Indeed, the GTTools are set up to work with in-Image sample data. Look at > implementors of #sample and #example. > There was quite some bike-shedding over the naming convention (and I forget > the final result), but hopefully it provide the general idea... > > http://forum.world.st/a-request-to-change-the-meaning-of-lt-example-gt-prag… > http://forum.world.st/lt-example-gt-lt-examplar-gt-td4911728i20.html > http://forum.world.st/Existing-lt-script-gt-lt-example-gt-pragmas-and-new-G… > > > > > > > I started, however, to question DI as a valid mechanisms because of it's > > complexities and other problems. The article from Fowler provides the > > service locator as an alternative which seems to me much simpler and > > completely fine solution for the problem. > > > > If it seems suitable, then to quote Nike, just do it ;) > > > > > So, to answer you question "Is it any more complicated than that?": In > > the DI approach, yes it can be, but I don't think so in the service locator > > approach. > > > > I am asking here because I wanted to know how people from Smalltalk deal > > with this problem. As it seems there is no standard approach, nor this is > > perceived as a problem... > > > > > DI or Service Locator are both "implementations" of your need. Can we take > step backward to see what is your need? To kick off, I hazard a guess at > some possible needs... > > 1. To switch between configurations to use production data and test data ? > 2. To make this switch during CI testing and production deployment ? > 3. To switch from the command line ? > 4. Want the configuration to editable remotely? e.g. from a text editor? > ? > ... > > > > > You think it is enough to do the wiring by hand? > > > > I'm having trouble understanding this "by hand" concept. > Don't you create the xml configuration file by hand? > You can just as easily > > > > > It is ok to use a service locator approach? Or wouldn't you care about > > that? > > > > If it works, its okay. > > So very generally, I'd avoid starting with any external test data, so as to > not distract myself by that implementation. > I'd copy-paste some test data into the class-side-methods of the domain > classes and hack some instance creation code around them. > Build your first tests around those. Then later, consolidate them via an > InImageTestData object that you'll later replace with ExternalTestData > > > > > > > > > but I'll add, it was so much simpler to understand without all that Java > >> typing boiler plate. > > > > > > Yeah, that's for sure! I am just used to read Java code. > > > > []s, > > Vitor > > > > > > > As an aside, try evaluting "Smalltalk tools inspect" > and debugging "Smalltalk tools browser open" > > cheers -ben

June 7, 2017