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

[Marc Hanisch via Pharo-users]

--- Begin Message ---
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 :

> 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
>
>
>
--- End Message ---

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

[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

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

[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: 'g...@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:  The directory of the local repository.
- commitDictionary:  Cached dictonary from 
commitId (hex string) to  all commits in the current branch (in the local repo).
- subdirectory:  The subdirectory of the local repository which is 
handled by the underlying GitFileTree
- versionDescriptors:  cached list of all 
package versions saved in the (currently selected branch) of the (local) 
repository.
- announcer: 
- branch:  currently selected branch. 
- loadedCode:   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 
>  wrote:
> 
> 
> From: Marc Hanisch 
> Subject: About patterns, UML and documentation
> Date: June 7, 2017 at 10:17:11 PM PDT
> To: Any question about pharo is welcome 
> 
> 
> 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
> 
> 

[Pharo-users] About patterns, UML and documentation

[Marc Hanisch via Pharo-users]

--- Begin Message ---
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
--- End Message ---