|
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. 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 |
