If you are going to
work with other people to build something, you need a way to communicate
clearly about what you are building.
From ages past, the clearest way to do that was by drawing pictures. With software, we do the same thing. Most tools, and methodologies have different
techniques, diagrams, and types of illustrations that are central to their
documentation approach. I'm familiar
with most of them. Over the years, I've
refined the best parts of each to construct a set of diagram that follows the
Key Principles and allows me to Move Quickly In the Dark.
The first is called
a Component Interaction Diagram, and the second is a Process Flow Diagram. In reality, all of the documentation formats
across the various methodologies and approaches have their strengths and weaknesses
and are proposed by smart people for varying reasons. With a Component Interaction Diagram (CID)
and corresponding Process Flow Diagram (PFD) we attempt to focus the diagrams
so that it provides the maximum value with the least effort and stays relevant
for the longest amount of time to the widest possible audience. Rather than try and justify the format up
front, I'm going to explain the how you create them. As we discuss each aspect of the diagrams and
the guidelines for them, the reasons for each will become apparent. If they don't, perhaps you'll find clear
reasons why you prefer whatever documentation you have chosen.
Component Interaction Diagram
A Component
Interaction Diagram (CID) has a singular purpose. It is depicts the components utilized in a
particular solution scope and the points of interaction between them. How it does that, the information that can be
layered on top of it or derived from it, and the variety of ways that it can be
utilized are all secondary considerations.
The way in which we meet the primary purpose is what will allow us to
use it to maximum advantage for the widest audiences. So as we go through the guidelines and
process of creation, consider all the downstream impacts and you'll understand
why it requires such rigid precision.
You'll also uncover areas where you can forgo precision or formality,
and the consequences of choosing to deviate.
In many cases, you may be perfectly happy with only reaping some of the
benefits, a decision which would merit following an abbreviated process.
Okay, with the
disclaimers and background out of the way, let us begin with the guidelines.
- A given CID should have a clear, identified and immutable scope that is independent of time.
- Use symbols to represent the components in scope for a given diagram.
- Use lines to represent interactions between the components in a given diagram.
- The consuming or external components are placed in the left most region in a given diagram.
- The persistent storage or most granular processes are placed in the right most region in a given diagram.
- Do not depict containment.
- Do not depict state, sequence, or directionality.
- Do not depict the flow of data or process logic.
- Environmental or grouping boundaries are an accepted practice.
- Use different symbols to represent components of different types.
- The set of symbols in use should be consistent across a given set of diagrams.
- Symbols should not contain other symbols.
- Every component should only exist once in a given diagram.
- Every component should have a unique identifying label in a given diagram.
- Classes, tables, and other structures containing state are represented as separate storage components.
- Methods, functions, and other processing constructs are to represented as separate process components.
- The should a minimal number of formats for lines in a given diagram.
- There should only be a single line between any two components in a given diagram.
- Every interaction line should connect exactly two components in a given diagram.
- Interaction lines should not have labels, but line format may indicate classification.
- Utilize call-outs to describe details in common language about a specific component or specific interaction.
- Utilize note boxes to provide context for a set of components or to describe the interaction semantics.
- Utilize note boxes to provide rationale for the approach, usage recommendations, or exception semantics.
- Always provide a legend for symbols and line formats if there are multiple.
Since the guidelines
are fairly rigid, let's discuss the intent and reasoning for the common areas
of concern.
A diagram should
have a particular scope independent of any particular processing state. Ensuring that every component only shows up
once on the diagram allows the diagram to serve as an inventory. By ensuring
there is no state or sequencing this allows us to track completion against the
inventory independent of the orthogonal or cross-cutting nature of the
components. Simply put, a component is
complete for a given diagram when it satisfies the interactions present on
given diagram. Enforcing that each component only shows up once allows for an
accurate depiction of multiple dependency and ensures that polymorphic or
iteratively developed components and functionality libraries are properly
decomposed.
Adding state,
sequence or flow to a diagram requires the introduction of time which modifies
the scope. The nature of state, sequence and flows means the diagram would not have a clearly delineated scope.
Introducing time information to a CID requires that the user understand the
particular pre- and post- conditions to validate the scope of the diagram. This
will inevitably complicate the diagram, often requiring multiple diagrams and
that the audience makes assumptions about the nature of the components or
interactions. All of these side effects
will allow a single diagram to have multiple interpretations which can all
appear accurate. For these reasons and
others this information should be represented separately in a Process Flow
Diagram using the symbols and components from this diagram.
For a particular set
of diagrams to be consumed easily by a variety of audiences, the information
needs to be presented consistently.
Therefore positioning components consistently within a diagram provides
the ability to perform comparisons between diagrams and to follow interactions
through symbols across different diagrams.
Components on a
diagram need to stand independently so that the their attributes can be
granularly managed for inventory, tracking, and validation. Containment makes calculation and attribute
management very difficult and can introduce artificial assumptions about
scope. Decomposition becomes unwieldy
and harder to validate with the introduction of containment. The use of bounding boxes or shaded
backgrounds for grouping is an accepted alternative but should be used
sparingly to reduce complexity and ease consumption.
The two major
classifications of components that are appropriate on a CID are components for
storage and for processing. Decomposing
processing components are usually self-explanatory with the only challenge to
find the appropriate level at which to stop.
Reasons to decompose below the assembly or interface boundary include
tracking the contributing teams, the use of different skill sets, or when
implementation is iterative. Consider
that every decomposition increases the barriers to construction and
consumption.
Deciding which
storage components to decompose can be challenging. As a general rule of thumb,
only persistent or shared data structures need to be present on the diagram as
storage components. For example, a class
that is used to transmit data across an interface isn't appropriate because it
is transitive (not persisted) and is only accessed by the components
independently. Alternatively an
in-memory class that manages thread state and is monitored by a controlling
process is shared but not persistent and therefore still meets the criteria for
placement on the diagram. A file which
receives log updates or a table which is updated as the outcome of a process
are both persistent and therefore meet the criteria for use on the
diagram. In any case, all data
structures for which you desire tracking can be included. Transitive structures
are strongly discouraged because of the complications involved with fitting
them into the diagram. Again, the trick
is to balance the desire to track at the most granular level against the ease
to construct and consume these diagrams.
Since my examples
are generally scrubbed for particular purposes you'll just have to contact me
if you'd like one.
