The Agile Modeling (AM) Method

Menu

UML Frames: Diagramming Style Guidelines

UML frames encapsulate a collection of collaborating instances or refers to another representation of such. Frames are depicted as rectangles with a notched descriptor box in the top left corner. Frames come in two flavors, a diagram frame such as Batch Transcript Printing and combined fragment frame such as the loop frame, both in Figure 1. Diagram frames explicitly define the boundary of a diagram whereas combined fragment frames encompass portions of a diagram or provide references to other diagrams or method definitions.
Figure 1. A frame encompassing a sequence diagram.

UML Frames: A Frame around a sequence diagram

Figure 2. Modeling alternate courses of logic.

Figure 3. The internals of the seminar component.

  1. Avoid Diagram Frames. The Batch Transcript Printing diagram frame of Figure 1 adds a significant amount of visual clutter in the process.
  2. Use Interaction Occurrences Over Part Decompositions. There are two references to logic external to Figure 1: the TranscriptBatch object includes a reference to PrintRun and there is a combined fragment referencing the SharedServices.print() method. The style of the first reference is called a part decomposition and the second an interaction occurrence.
  3. Fully Specify Operation Names in References.
  4. Depict One Interface Per Port. Ports are connection points between a classifier and its environment. Ports are depicted on the side of frames as small rectangles.
  5. Depict One Port Per Realizing Class. See also UML interface style guidelines.
  6. Deemphasize Frame Borders. In Figure 1 you see that the frame border is lighter than the lines around it.
  7. Apply Standard Labels to Descriptors. Table 1 summarizes common labels for diagram frames and Table 2 the common labels for combined fragments.

Table 1. Diagram frame labels.

Label Usage
Component The frame depicts the internal design of a component.
Package The frame depicts the internal organization of a package, often using a UML class diagram or a UML use case diagram.
sd Indicates that the frame contains an interaction diagram, usually a UML sequence diagram although UML communication diagrams are also common options.
Use Case The frame depicts the logic of a use case, often as a UML activity diagram or a UML interaction overview diagram.

Table 2. Combined fragment labels.

Label Usage
alt Indicates several alternatives, only one of which will be taken, separated by dashed lines. Used to model if and switch statements. See the example in Figure 2.
assert Indicates that the fragment models an assertion.
criticalRegion Indicates that the fragment must be treated as atomic and cannot be interleaved with other event occurrences. Often used within a par frame (Douglass 2004).
loop Models logic which will be potentially repeated several times.
opt Models optional logic depending on the run-time evaluation of a guard.
par Indicates several fragments of logic, separated by dashed lines, all of which will run in parallel.
ref References another diagram or a method definition.

Recommended Reading

Modeling style: Elements of UML 2.0 Style The Elements of UML 2.0 Style describes a collection of standards, conventions, and guidelines for creating effective UML diagrams. They are sound, proven strategies that lead to diagrams that are easier to understand and work with. These conventions exist as a collection of simple, concise guidelines that if applied consistently, represent an important first step in increasing your productivity as a modeler. This book is oriented towards intermediate to advanced UML modelers. Although there are numerous examples throughout the book it would not be a good way to learn the UML (instead, consider The Object Primer). The book is 188 pages long and is conveniently pocket-sized so it’s easy to carry around.
Choose Your WoW! 2nd Edition This book, Choose Your WoW! A Disciplined Agile Approach to Optimizing Your Way of Working (WoW) – Second Edition, is an indispensable guide for agile coaches and practitioners. It overviews key aspects of the Disciplined Agile® (DA™) tool kit. Hundreds of organizations around the world have already benefited from DA, which is the only comprehensive tool kit available for guidance on building high-performance agile teams and optimizing your WoW. As a hybrid of the leading agile, lean, and traditional approaches, DA provides hundreds of strategies to help you make better decisions within your agile teams, balancing self-organization with the realities and constraints of your unique enterprise context.
The Object Primer 3rd Edition: Agile Model Driven Development (AMDD) with UML 2 The Object Primer 3rd Edition: Agile Model Driven Development with UML 2 is an important reference book for agile modelers, describing how to develop 35 types of agile models including all 13 UML 2 diagrams. Furthermore, this book describes the fundamental programming and testing techniques for successful agile solution delivery. The book also shows how to move from your agile models to source code, how to succeed at implementation techniques such as refactoring and test-driven development(TDD). The Object Primer also includes a chapter overviewing the critical database development techniques (database refactoring, object/relational mapping, legacy analysis, and database access coding) from my award-winning Agile Database Techniques book.