I am working with Bursatec, the technology company of the Mexican stock exchange on the architecture design for a new system. Bursatec is using the SEI’s Attribute-Driven Design (ADD) method embedded in a Team Software Process (TSP) environment for designing the new system. They also use the tool “Enterprise Architect” for documenting the system’s software architecture.
Last week, when working with Bursatec’s architecture team, they showed a nice little rule they implemented for using the design tool. Since I believe that many architects have the same problem when using a design tool, I thought it would be worthwhile sharing their solution.
Often the problem with design tools is that they try to help when it is inappropriate and don’t help when it would be appropriate. In our case, Carlos Patiño, Israel Correa, and Hugo Hernandez, three members of the architecture team, came up with a workaround for a feature where the tool tries to help when it shouldn’t. Here the problem:
Assume you have a set of architecture elements. Assume also that those elements are modeled in the Enterprise Architect tool by using UML classes. Now you want to describe how those elements interact with each other to realize the use cases that are defined for this system. To do so, you use the tool to define operations for the architecture elements and you use the operations in sequence diagrams to describe the sequence of interactions for a use case. You will create diagrams similar to this.
So, for example you have an element called “ClassB” with the operations “getValueA” and “getValueB.” Both are used by the element “ClassA.”
So far so good; no problem yet.
The problem arises when you have many of those diagrams, let’s say more than 100, which is not that uncommon. During the architecture work, it is likely that you discover that some of the operations you defined before are actually wrong. For eample, you may have discovered that the operation “getValueB” of the element “ClassB” actually should be separated into two operations, which should be “process” and “retrieve.” Clever as we are, we rename “getValueB” into “retrieve” and we add a new operation “process.”
As soon as we do that, the tool starts “helping” us. It renames “getValueB” in all diagrams to “retrieve.” So we get the following diagram:
Unfortunately, the change in the operation we made was not just a syntactic change. We changed the meaning of the operation too, which cannot be supported by the tool. In reality we want to describe something like using “process” first and then use “retrieve.”
That means we now have to go to every sequence diagram in which the operation “getValueB” was used and check if we have to change the diagram. This is much more difficult than it sounds. Sequence diagrams usually are larger than our simple example here.
They look more like this:
Don’t worry if you cannot read that diagram. I do this intentionally to emphasize the difficulty in finding something in a sequence diagram (and of course to protect the intellectual property of Bursatec).
To find the places in the current sequence diagram where the “getValueB” operation was used, you first you have to remember to look for “retrieve” and not “getValueB.” Then you have to make the appropriate adjustments. If the diagram has 30, 40, or even more interactions, which is quite normal, then I bet that you will miss some.
Now here is the solution our friends Carlos, Israel, and Hugo came up with. They decided to not to reuse the old operation “getValueB.” Instead they renamed the operation into “DELETE.getValueB” and added the two new operations “process” and “retrieve.” Very simple, but very powerful. By renaming the operation in this way, they effectively created a marker that is shown in every affected diagram and is easy to spot.
If for whatever reason you display such a diagram, even the untrained person recognizes this operation and will ask: “What is this?” If the description of the operation also includes a description on how to substitute this operation with “process” and “retrieve,” then it is much easier to achieve consistency.
If you have similar little tricks on how to use your favorite design tool, please share them with us.
— Felix Bachmann, SEI