I've been a zone leader with DZone since 2008, and I'm crazy about community. Every day I get to work with the best that JavaScript, HTML5, Android and iOS has to offer, creating apps that truly make at difference, as principal front-end architect at Avego. James is a DZone Zone Leader and has posted 639 posts at DZone. You can read more from them at their website. View Full User Profile

Do You Let Your UML Diagrams Go Stale?

05.13.2010
| 7613 views |
  • submit to reddit

In today's DZone links there's a post about a new UML tool, Architexa . The idea of the tool is that it provides you with an easy way to view UML diagrams of your code from your IDE. Check out their video: 

I guess the idea isn't new, a few UML tools provide reverse engineering functionality. It's made me wonder, do most developers let their initial designs go stale once they get into the coding? Personally, I'd rather that the diagrams are always up to date, but I recognise that sometimes it can be too much work to go back and update diagrams once the coding process is underway. Especially when under a tight deadline.

UML diagrams are central to my ideal review process. Obviously, I need the diagrams to carry out a design review. I like to use the diagrams for part one of a code review too, so that I can ensure that the code aligns with the original design. A tool like Architexa gives me the opportunity to compare the original design and a design that accurately reflects the actual code. 

Now, to the point of this poll, do most developers ignore the original designs? Or is there some kind of update process that you use? I'd be interested to hear your thoughts on the importance of design artifacts once code exists. 

Comments

Fabrizio Giudici replied on Thu, 2010/05/13 - 4:26am

I cast my vote to "I use some tooling to reverse engineer from code to UML diagrams" as I use UMLGraph to reverse engineer code into my JavaDocs, even though I really do a mix of all the three choices :-)  "manual update", as using UMLGraph which permits annotations in the code that control the way the UML is rendered, and in the end everything goes into the code, which "is the most important artifact".

Alex(JAlexoid) ... replied on Thu, 2010/05/13 - 6:23am

I hate to say it, but UML diagrams have become a nice to have feature.

The only 2 places where I find them useful:

  1. Core "framework" or base features(call it however you like) - the things that are used by at least 50% of the code
  2. Very high level diagrams - packages(and anything above) and package interdependencies
Everything else is just too dynamic to waste time on.

Raveman Ravemanus replied on Thu, 2010/05/13 - 7:55am

There should be 4th option - i dont believe in value of uml

Vineet Sinha replied on Thu, 2010/05/13 - 8:26am

I think there is something missing in the post here, i.e. there is a difference between what we *want* to do and what we are *able* to do.

For a 4+ developer team, I think the design is the most important followed by the code. But, constraints on the project make it really hard to keep up on this design - and we all end up falling back on the code.

Now, I might be biased, but the best tool that we have to manage design is UML. And therefore it is only UML (or UML-like) tools that need to help with not only (a) designing in the beginning as they currently do, but also (b) supporting keeping the design up-to-date as the project evolves - i.e. the 90% of the development cycle.

With that thought, tools that can reverse-engineer are important because otherwise the diagrams will go stale, but more important are the tools that can help us have do the smallest amount of manual work to have these tools help us. Tools like UMLGraph and Architexa are the right solution in this regard - it is just that Architexa also helps in guiding you and making the 'reverse engineering' part easier.

So yeah, I was also thinking that there should be an 'all of the above' option.

- Vineet
Architexa: Know Your Code

Vineet Sinha replied on Thu, 2010/05/13 - 8:42am in response to: Alex(JAlexoid) Panzin

Alex, good points.

Everything else is just too dynamic to waste time on.

But what about important use cases in the application?

The way I look at it is there are three really important aspects to every system the high level view (your #2), the core 'concerns' (your #1 plus a little more), and the important use cases. The not so surprising thing, is that the most popular type of diagrams in software projects have their strengths in just these: layered architectural diagrams, class diagrams, and sequence diagrams respectively.

- Vineet (Architexa)

Dhaval Nagar replied on Thu, 2010/05/13 - 9:33am

This seems very exciting and fun to work with. Me and my team faces hard time whenever we need to generate diagrams from the code base with zillions of tools we use for diagramming.

We use NetBeans IDE for all our development and prefers external tools which can easily integrate with it. I guess we need to wait to get this on NetBeans but the YouTube presentation is impressive enough to make team ready to use Eclipse for diagramming.

Dhaval Nagar replied on Thu, 2010/05/13 - 9:46am

Well I am not sure whether this is the correction question or not but as per my understanding through YouTube presentation it works on the code base and not on the execution flow (???) specifically for sequence diagrams.

In one of my last system we used Spring AOP and Annotations extensively and to get correct sequencing as per use cases we had to wait until the runtime so we used jTracert (which is now jSonde).

Will this tool be helpful in such execution flows?

Vineet Sinha replied on Thu, 2010/05/13 - 12:08pm in response to: Dhaval Nagar

Dhaval,
The system does not depend on runtime information but can take advantage of it when given. This allows us to not have the performance limitations of the runtime tools, but allow users to view any execution possible from the code.

We have added 'scripts' to show take into account stack traces and are adding support for various xml specifications. We can also add support for Spring AOP and/or using runtime information as done by jTracert.

- Vineet
Architexa: Know Your Code

Travis Calder replied on Thu, 2010/05/13 - 1:29pm in response to: Vineet Sinha

I think the best took for a team isn't UML, it's communication. UML is just one way to communicate.

If what your team needs is a way to discuss a design up-front, hand-drawn UML is a reasonable approach. Just make sure to throw it away - it can't go stale in the shredder.

If what your team needs is a way to visualize the current design quickly, a good reverse-engineering tool is a reasonable solution. These don't go stale.

If you need up-front design AND ongoing visualization, then do both. Have a hand-drawn one you throw away, and a reverse-engineering tool that shows your current behaviour.

The actual solution almost never ends up being the same as your first attempted design, except in very simple systems, and the only thing worse than no documentation is stale documentation.

(+1 for "All of the Above")

Fabrizio Giudici replied on Fri, 2010/05/14 - 4:56am

@Alex, of course I agree, things that aren't exposed APIs or high-level stuff aren't worth while wasting too much time.

Justin Forder replied on Fri, 2010/05/14 - 11:52am

I favour:
  • Initial UML (or similar) sketches on whiteboard, photos processed with WhiteboardPhoto. Fragments of class diagrams, sequence diagrams, and also 'storyboards' of significant change scenarios in terms of instance diagrams annotated with changes, or 'before' and 'after' snapshots of relevant instances and associations.
  • Reverse engineering to class diagrams using Enterprise Architect, often to help me understand and review a project's code, but also for communication, e.g. where class diagrams are needed for inclusion in documentation.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.