Sequence Diagram Editor

practical sequence diagram creation software

 
 

UML Sequence Diagrams - Common Mistakes 

This section describes some common mistakes related to the use and development of sequence diagrams for software and system level design.

UML Sequence Diagrams that are Too Low Level

In our experience, the closer one gets to the source code level, the less useful and valuable sequence diagrams become. This is because sequence diagrams at this level tend to only give you redundant information that you could have easily obtained from just looking at the source code.  We're not suggesting that they should never be used at this level, you just have to be more careful about choosing the right scenarios to document.

At the source code level, you should primarily use sequence diagrams to design or document complex logic involving interactions between multiple objects. You should not use them, for example, to describe the logic of a method or a straightforward scenario unless you have a very good reason to do so.

One exception to this guideline is for state machine based designs where one or more objects have to follow a long and complex sequence of actions (with possible branching and special cases) to accomplish a task, especially when the triggers for each action are external messages or events. In this case, sequence diagrams are valuable because they show the sequence of events (including state transitions and timers) that occur for each particular scenario, which can often be difficult to visualize directly from the source code.

We've witnessed first hand the value that sequence diagrams can provide while designing and implementing state machine based software systems while working at the source code level.

Another typical mistake when working with sequence diagrams is adding too much detail. Just because your code has several branches in a particular method doesn't mean you should include each one (or even any of them) in the same diagram using block or scenario elements. Adding too much detail just ends up cluttering the diagrams and making them more difficult to read and understand. The same holds true for sequence diagrams at the system level. Just because there are alternate scenarios doesn't mean that you have to document all of them in your diagrams.

Trying to Document Too Many Scenarios Using Sequence Diagrams

Another common mistake is attempting to create a sequence diagram for each and every possible scenario in the system, particularly when designing close to the source code level. If you can imagine documenting every single click on your broadband bill, it becomes an impossibly lengthy and ultimately time-wasting task, and the same goes for creating multiple sequence diagrams for scenarios that can be documented with common sense. As Scott Ambler suggests, teams can waste away months of effort elaborating each and every use case (including all alternatives) even when the use cases are simple and straightforward.

When working at higher levels (such as the unit or component levels) or with state machine based objects, it is a good idea to include general purpose documentation diagrams describing the basic course of action for the common operations in the system and a few of the more interesting alternatives. If there are complex special cases or "gotchas" that need to be handled, they should also be documented as alternatives or even as separate diagrams.

Even straightforward or simple scenarios are worth describing at higher levels because they document the expected system behavior and the normal interactions between the different units.

Not Enough Scenarios Covered by Sequence Diagrams

At the other extreme is the mistake of having too few sequence diagrams covering only parts of the most basic scenarios.

Sequence diagram editor makes it possible to create a more complete and useful set of diagrams to document the basic scenarios as well as design for alternatives and special cases.

Sequence Diagrams that are Obsolete and Out of Date

Sequence diagrams that are allowed to become so outdated that they are nowhere close to the actual architecture, interfaces or behavior of the system become a hindrance since they stop providing any real documentation value. This is another reason why higher level sequence diagrams work better than low-level diagrams; they tend to remain relevant even as the implementation details are changed or refactored; often, they require only small modifications over time to remain up to date.

If you find yourself making large enough changes that impact your high-level diagrams, the process of updating the sequence diagrams to match the new design can itself be a valuable exercise for detecting problems early on.

Another useful approach is to use diagram link elements to abstract detailed operations and keep the top-level diagrams neat and simple. The detailed operations can be elaborated in separate diagrams and then reused by many of the top-level diagrams. You may even choose to avoid elaborating certain operations entirely because they are too detailed for the current diagram level.

Download Sequence Diagram Editor for a Risk Free 14-Day Trial

Sequence Diagram Home

Buy Now

Download Free Trial

More Information

Screenshots

Sample Diagrams

Documentation

Technical Support

Contact Us

Press

Resources

Only $99

Volume discounts available

Works with Windows 2000, Windows XP, and Windows 2003 Server, Windows Vista, Windows 7

Comments

Great tool... nothing but praise for its ease of use and usefulness

-- Ian Taylor,

XCV Pty Ltd

 

I've been evaluating your software package. It's phenomenal. Having normally used Visio for sequence diagrams I'm used to spending too much time monkeying with how the diagram looks and keeping it consistent. Your sequence diagram editor gives a better graphic presentation and captures additional information.

-- Name withheld by request

 

 


Visio UML Sequence Diagrams

Copyright 2005-2009 Effexis Software, LLC. All rights reserved.