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
