Adding Structure to Our Lives

UML and SysML classify diagrams as showing structure, interactions, or behavior.  Structural diagrams show the system's pieces and relationships among those parts.  Interaction diagrams show the communications among those pieces.  Behavioral diagrams specify how the pieces respond when they receive messages.  (Please note:  I used the term "pieces" specifically because it is not a UML or SysML term.  A piece could be a class, object, file, structure, block, or part) Structure diagrams serve similar purposes in both UML and SysML, it with some important differences.  For Systems Engineers, the entities represent abstract concepts about a system's decomposition.  For software developers, the entities represent code that will be created (i.e., generated or handwritten) to implement the software application. The next few articles discuss structural diagrams.  

Coding, designing, and modeling

"How can I do my design when I haven't written the (expletive deleted) code yet?" a former colleague yelled quite irately as I passed by a manager's office.  Now I know Joe.  Yes, sometimes he would start out coding and end up with some useless methods and classes.  But Joe always had an idea of his code's basic structure.  What Joe meant to say was that he could not write the detailed documentation of his design because he hadn't worked out all the details yet.

Unfortunately, many developers look at modeling the way Joe looked at design -- as a documentation step to be completed rather than something that helps the goal of producing properly executing code quickly and efficiently.

Modeling helps developers visualize the structure, interactions, and behavior of the system they are building (NB:  I used the plural because developers seldom work alone.  One must be able to communicate one's ideas;  more on that in another article).

In fact, in a 2008 survey by Scott Ambler found that the vast majority of developers used high level diagrams.  From my own practice, I'm assuming that the majority use class diagrams to define structure. I'll bet that a fair number of developers use some variation of sequence diagrams when discussing interactions as well.  Here is my point:  If you are already using these two common diagrams, why not capture the artifacts in a tool rather than on a white board?  Doing so makes the artifacts reusable and captures the design rationale for the rest of the team (including reviewers and maintainers).

Bottom line:  if Joe had captured his thoughts in a model, he wouldn't have had the scream match with his boss.  He might even still be working there.

Refining Use Cases with Activity Diagrams

In a previous post, I discussed text based use case descriptions. This post discusses a graphical method:  activity diagrams.

Before discussing the advantages of refining use cases with activity diagrams, let's define activity diagrams.  One of my colleagues describes them as "flow charts on steroids."  Activity diagrams show the possible sequences of activities and the flow of data between activities in a single view.

The rectangles with rounded corners represent activities.  In the software world, an activity would be implemented as a functions or method.  On this diagram, the dashed red lines represent the order  that the actions occur.

Unlike text, graphical activity diagrams are not open to interpretation.  Even people not trained in UML's or SysML's subtleties understand an activity diagrams flowchart-like structure.  Complicated concepts, including exception condition handling, become clear when viewed on a single page.


Note that you may use nested activity diagrams (not what they are called, we'll get to the proper name later) to describe complex actions.

 In summary, the advantages of using activity diagrams to refine use cases include:

• Graphical representation is not open to interpretation the way text is
• Shows multiple paths (including exception conditions) in one view
• Complex actions may be further refined with other activity diagrams