It's not a secret anymore!*
The moose likes OO, Patterns, UML and Refactoring and the fly likes Current UML Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » OO, Patterns, UML and Refactoring
Bookmark "Current UML" Watch "Current UML" New topic
Author

Current UML

Marc Bautis
Greenhorn

Joined: Sep 17, 2004
Posts: 6
I work on a development team just starting to use UML. One of the things we would look to use our diagrams for would be to give to new team members to help them get up to speed with our applications.

How is it possible to ensure that the UML is kept up to date. By that I mean when a developer makes a change to the source code to fix a bug or for a new release they often do not go an update the UML diagrams
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
1) Always model first and forward generate code. Usually impractical, requires excellent forward generation tools.

2) Regularly reverse engineer from code to model. Almost always impractical, models every single method and utility class to excruciating detail so the model is harder to read than the code.

3) Stand over developers with a large stick and remind them to keep models up to date. Might be fun if you're holding the stick.

Seriously, Scott Ambler's Agile Modeling style encourages you to think about what models you don't have to keep. Given the problems above this turns out to be most of them. Incorrect documents are pretty dangerous stuff if you have one of the rare groups who ever reads them.
[ September 23, 2004: Message edited by: Stan James ]

A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Scott Ambler
author
Ranch Hand

Joined: Dec 12, 2003
Posts: 608
You should recognize that you don't need to keep many of your diagrams, that's traveling heavy, nor do you even need to keep them up to date. Good docs are high-level and concise, therefore are far less likely to get out of date. Focus on developing really clean code, you'll find that you don't need as much documentation as you think.

- Scott


<a href="http://www-306.ibm.com/software/rational/bios/ambler.html" target="_blank" rel="nofollow">Scott W. Ambler</a><br />Practice Leader Agile Development, IBM Rational<br /> <br />Now available: <a href="http://www.ambysoft.com/books/refactoringDatabases.html" target="_blank" rel="nofollow">Refactoring Databases: Evolutionary Database Design</a>
Sathya Srinivasan
Ranch Hand

Joined: Jan 29, 2002
Posts: 379
Whenever you use UML, remember that the people who you ask to write UML might not be as proficient in it as you might assume.

I fully agree with Stan's observations. They are almost exactly what happened in one of my projects. It takes extreme discipline to maintain a consistent relationship between your diagrams and code, a discipline that almost often is impractical.

Ask yourself what diagrams are really needed. Typically, some sketches of class and sequence diagrams should be more than sufficient to elucidate fine points.

Instead of emphasizing on UML, try to get your developers to document the code better using Javadoc or even by making them write test cases with proper names. This goes a long way in explaining the code than the diagrams.

One mechanism that I used in a project was to draw the diagrams on a whiteboard as a part of brainstorming and then simply capturing it as an image (with digicams, this is a cinch). That done, you can paste it in your documents, or if it is client-facing, ask someone to redraw it in a popular tool and paste it in the document.


Cheers, Sathya Srinivasan - SCJP 1.2, SCWCD 1.2, SCMAD 1.0
Co-Author of Whizlabs SCMAD Certification Exam Simulator and SCMAD Exam Guide Book
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Marc Bautis:
One of the things we would look to use our diagrams for would be to give to new team members to help them get up to speed with our applications.


The best way to let new team members become productive I know is Pair Programming with them. That way, they learn the system from experience instead of dull paper and can contribute from day one, for example by asking "dumb" questions. The pair might also want to sketch a JIT UML diagram from time to time, of course.


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
Lest we sound like anarchists who frolic drunkenly around documentation bonfires, let's admit some possible Uses of Architecture Documentation. As you consider what models and diagrams can be discarded, also consider which might have value for the purposes described here.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Current UML