> > 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.hani...@googlemail.com> > To: Any question about pharo is welcome <pharo-users@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 jtuc...@objektfabrik.de <jtuc...@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:jtuc...@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 > > > > > >
