Win a copy of Design for the Mind this week in the Design forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Current UML

 
Marc Bautis
Greenhorn
Posts: 6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 8791
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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 ]
 
Scott Ambler
author
Ranch Hand
Posts: 608
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Sathya Srinivasan
Ranch Hand
Posts: 379
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Stan James
(instanceof Sidekick)
Ranch Hand
Posts: 8791
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic