Inside VSTS

The Joy of Sequence Diagrams

Rosario features a new and improved kind of class diagram. Jeff dives into the details.

• By Jeff Levinson
• 05/07/2008

The Logical Class Diagram
Why do we need another class diagram? After all, Visual Studio already includes a class diagram which does a pretty good job, right?

OK, anyone who's used it before knows that there are serious shortcomings with the existing class diagramming tool. You can't represent namespaces or container hierarchies (i.e., Class A is in Namespace B which is in Assembly C), and you can't show classes from multiple projects on a single class diagram since these diagrams are specific to a project and not a solution.

Enter the LCD. The LCD allows you to do just what you can't do with a standard class diagram. Figure 1 shows the LCD used to lay out two different projects: the PubsUI and the PubsMiddleTier. You can see the ability of the diagram to roll up packages, represent relationships between objects and show classes in different projects.

The Sequence Diagram
The LCD is a key component of the SD because it's the only place (currently, anyway; whether this is the case by release time isn't yet known) you can add classes onto the SD without reverse-engineering an entire sequence from the Architecture Explorer. The SDs are UML 2.x-compliant, allowing you to start reusing and creating more elaborate SDs which actually make understanding code easier.

The first part of any good documentation structure is reuse. In SDs, this is implemented with the ref object. In Figure 2, clicking the arrow in the EmployeeController dialog will open the EmployeeController sequence diagram. In this way, you can take common sequences and embed them in other sequences and still have to make a change only in one place if the common sequence changes.

Another feature of good documentation isn't to include too much documentation. Include just enough to make it understandable. Figure 3 shows two examples of how the Sequence Diagram makes complex items easy to read with a minimal amount of overhead. The first is the loop depicted on the EmployeeLogic class, which is an example of a combined fragment. You can use it to represent a number of items from a sequence to an alternate path or an option or so on. In this case, it's depicting the fact that there's a loop in the GetEmployeeList. Typically, you'd use the loop to indicate a series of actions across objects, but it also shows where potential issues in an application are.

The second feature is the Lost Found Target on the EmployeesForm lifeline (black dot). This is used to indicate several different things but, in this case, represents a recursion on the forms constructor (because of how forms are constructed, I created a second constructor which calls the first constructor, hence the recursion). Instead of representing each and every call in the recursion, you can simply represent it once, acknowledge that it's there and move on.

One More Thing...
Finally, a word about the diagrams in Rosario. One of the problems with the initial set of diagrams in VSTS 2005 and 2008 is that the only information on the diagrams was semantic pieces of information. That is, they represented something concrete and could be implemented (or were already implemented). This made communicating ideas very difficult.

The benefit of the revamped diagrams is that not only can the represented information be semantic, but it can also be non-semantic. That is, it can be used to communicate ideas and thoughts without adding any particular constraints to a solution. This makes the new suite of diagrams in the Architecture Edition particularly powerful and useful.