Channels ▼

Tracing Your Design

April 1999: Design Center: Tracing Your Design

At several points in your current project, some are going to say the “T” word: traceability. They’ll want to ensure that your project achieves full requirements traceability. Most systems professionals would respond that of course requirements will be traceable, regardless of whether this is true.

It’s rare to find a software project team that can honestly claim full requirements traceability throughout a project, especially if the team uses object-oriented technology. Requirements traceability is complex, requiring integrated tool support and project team members who thoroughly understand the software development process. Although I’m not going to help you select tools, I will focus on how requirements traceability works for object-oriented projects.

In this article, I’ll discuss requirements traceability and why it’s important. I’ll then delve into traceability between the different Unified Modeling Language (UML) models, showing how consistently using the object paradigm’s underlying fundamentals in UML can enhance traceability. Because the UML is not yet sufficient for the complete development of business application software, I enhance the UML models I choose with additional deliverables from the Rational Unified Process (RUP). Further, because the RUP isn’t complete either (its scope is a single project and not a collection of projects, which most enterprises actually have to manage), I’ll extend my design with a couple of deliverables to fully round out my discussion. Finally, I’ll discuss traceability issues throughout the life cycle for incremental and iterative development, the norm in today’s world.

What Is Requirements Traceability?

In Matthias Jarke’s article “Requirements Tracing” (Communications of the ACM, 41(12), 1998), Jarke defines requirements traceability as the ability to describe and follow the life of a requirement, in both a forward and backward direction, throughout the system life cycle. There are two interesting concepts in this definition. First, traceability is defined in both forward and backward directions, implying that for any feature of any deliverable, you should be able to trace that feature to its initial source as well as to its ultimate implementation. For example, you should be able to trace a member function (also called an operation or method) of a class within your design model backward to the portion of the use case that defined its motivating requirement. In turn, you should be able to trace that information back to the initial source, likely several users, who provided the material captured in that use case. Further, you should be able to trace the member function’s definition forward to the source code that implements it.

The second point this definition makes is that you should perform traceability throughout the entire system life cycle. As you can imagine, defining the system life cycle’s scope is as important as the traceability level within your project. Figure 1 depicts the true context of the system life cycle. Note that I don’t use the term system development life cycle (SDLC), a misnomer that has led many software professionals to mistakenly believe that you only need to concern yourself with the development of software, and not its continuing maintenance and support (nor the business environment it will operate in).

Figure 1

In the context of the system life cycle, you need to trace requirements from their initial source. You can do so either through direct users describing their needs, management describing the organization’s long-term needs and environment, or through development into the system’s maintenance and support. Although the RUP life cycle shown in Figure 3 does not include an explicit maintenance and support phase, never forget that a good developer knows there is more to development than programming, but a great developer knows there is more to development than development. To be successful at requirements traceability, you must choose to be great.

Although few people worry about the type of trace they’re applying, it is important to understand that there are four different types because it reveals why requirements traceability is important to your project.

Type One: Forward from requirements. With this trace type, you assign responsibility for fulfilling a requirement to the various system components that will implement it, letting you ensure that each requirement is fulfilled.

Type Two: Backward to requirements. This trace type, the opposite direction of the first type, verifies compliance of software built to requirements. Software features that you cannot trace back to requirements indicate one of two problems: missing requirements or, more likely, goldplating. Goldplating is adding superfluous features that aren’t motivated by actual requirements.

Type Three: Forward to requirements. This trace type maps stakeholder needs to the requirements, so that you can determine the impact to your requirements as needs change. Changing needs, either from a change in strategy, an increased understanding of the problem domain, or an environmental change, is a reality of the software industry and an important issue that must be managed effectively.

Type Four: Backward from requirements. This trace type lets you verify that your system meets the user community’s needs, an important consideration when you attempt to justify your budget. It is important to understand the source of your requirements—a requirement from a key customer likely has a different priority than one from a junior programmer.

Why Requirements Traceability?

From a business point of view, requirements traceability offers a couple questionable benefits, but it offers four real benefits from the software engineering point of view.

First, requirements traceability lets you align your changing business needs with the software your organization developed. This improves both the effectiveness of the software being developed and the productivity of your information technology department (its mission should be to develop software that your company actually needs).

Second, requirements traceability reduces risk by capturing knowledge that’s vital to your project’s success. When someone leaves your company, you lose his or her knowledge about the software that he or she was responsible for without traceability (and considering the current job climate, most organizations have this problem). It is often expensive, if not impossible, to regain this knowledge once it’s lost.

Third, requirements traceability lets your organization determine the impact of a change to the system requirements. When requirements are traceable into the software that implements them, you can easily determine the time required, cost, and potential benefit of a change. Firms that trace requirements and capture meaningful links between development deliverables can determine the potential impact of changes to their software and choose to invest in the changes with the best payoff. Firms that do not trace requirements must invest their money blindly, often throwing it away on changes they can’t reasonably justify. In short, requirements traceability makes you smarter and saves you money.

Fourth, requirements traceability supports process improvement by helping you understand what you’ve actually done. If you understand how you build software, you can identify where your staff is having difficulties, often unbeknownst to them, and help them improve the way they work.

Business benefits that are at best questionable, and at worst detrimental, include contract compliance. One of the greatest motivating factors for tracing requirements is that contracts require companies to do so. In these situations, more often than not, the company will do just enough to comply with the contract but nothing more. Its traceability efforts typically become bureaucratic and onerous, quickly devolving into a paper-pushing effort. This information is seldom used to improve either the software being developed or the software process itself. The goal of securing the contract is achieved but little benefit beyond that is gained, and developers are often completely soured on the concept of requirements traceability.

A second questionable motivation for tracing requirements is to protect yourself against criticism or liability lawsuits. Making sure your backside is covered should not be your only motivation if you want to achieve any real benefits from requirements traceability. Firms that are interested in protecting themselves from liability lawsuits usually know they are in serious trouble. As a developer, do you really want to work for an organization that must employ lawyers at the end of a project to prove that you actually did your job?

When to Trace Requirements

You should trace requirements continuously throughout your project. You should start when you identify the initial requirements for your system, typically during the Inception phase. (A figure that illustrates the four-phase life cycle of the RUP, including the Inception phase, is on page 58 of this issue). During the Inception phase, you will likely develop an initial user interface prototype, and this prototype should be traceable to the business requirements that motivated it. In fact, your tracing efforts will help you better flesh out the requirements and produce a more effective user interface. Tracing aspects of the user interface back to your requirements helps you ensure that the user interface meets those requirements.

Tracing continues through the Elaboration phase as you improve your requirements model and define the architecture that meets those requirements. Tracing your requirements to your architecture model helps ensure that the architecture meets those requirements, and often helps you discover new requirements (such as performance and platform-related issues) that you missed earlier.

You will also trace requirements through the Construction phase, tracing your requirements to your models, then to your source code that implements those models, and finally to the unit test cases used to verify your code. Tracing your requirements through your models lets you once double-check that your software fulfills its requirements and can identify requirements that are either missing or misunderstood. Tracing how your models and code fit together lets you discover redundant or inconsistent work quickly.

Requirements traceability is important during the Transition phase because your function test cases will be traced back to the initial requirements, which lets you show that the delivered software meets its defined requirements. Traceability also lets you quickly find the portions of your software that failed testing, reducing the time needed to fix it.

Finally, when your system enters the Maintain and Support phase, a phase the RUP doesn’t have yet, you still need to do traceability as problem reports and new requirements are identified. Your change control board should review these potential changes, perform an impact analysis, and assign them to future releases of your system. To get a better feel for what the Maintain and Support phase should contain, Figure 2 presents the process patterns of the object-oriented software process (OOSP). In a future article, I will show how you can use process patterns to enhance and extend the RUP to meet your organization’s needs.

Figure 2

You can and should trace requirements continuously through your project. First, requirements traceability can improve your project by making it more comprehensive. Second, and more important, the benefits of requirements traceability are gained throughout the entire software process, not just at the beginning and end. Many organizations leave their tracing efforts to the end of the project life cycle. Typically, these organizations are either concerned about liability issues or are contracted to do so. Frankly, this offers little value and in practice proves to be wasteful, time-consuming work.

Traceability and UML

There are two basic issues to address regarding traceability and the UML: How does UML support traceability, and what should you trace? The first question is the easiest to answer, UML supports traceability via the trace stereotype. To indicate traceability on your models, you simply model a dependency from one item to the other item, draw a dependency as a dotted line with an open arrowhead, and label it <<trace>>. Stereotypes, indicated with the <<some text>> notation, are a UML mechanism for extending the modeling language by defining common types that are appropriate to your problem domain. The trace stereotype is one of several common stereotypes suggested by the UML standards. It is applicable to all model types, as are the <<uses>> and <<extends>> stereotypes that are applicable to use case diagrams.

The bad news, however, is that simply drawing a line and putting a label on it isn’t enough. You also need to document why something traces to something else, perhaps the design decision that was made when you traced a step of a use case to a method of a class. Knowing who documented the trace, so that you can contact them later, is good information to record. Finally, knowing when the trace was made can help you understand the motivation behind the trace. If you didn’t know why there was a trace to an older version of a class library, knowing the date would reveal that the library was the most current one at the time.

The second issue is more complex because it asks what you need to trace between the different diagrams of the UML—or, more important, between the potential object-oriented development deliverables. For example, you can extend the diagrams of the UML, such as sequence diagrams and class models, with the RUP deliverables, such as project plans. You also might need change cases, descriptions of potential requirements that your system may need to support in the future, to meet the needs of a large-scale, mission-critical effort, something that goes beyond both the UML and the RUP. I’ll discuss this more later.

For years, you probably heard that the object paradigm was based on a set of straightforward and simple concepts—such as encapsulation, polymorphism, inheritance, and aggregation—but may have never realized the implications of this. Tracing between UML diagrams should reveal the importance of the object paradigm’s underlying consistency, shown by the high level of traceability between deliverables. The bottom line is that this underlying consistency supports and enhances traceability between deliverables: in many cases, you merely trace a single concept from one deliverable to another.

For example, consider the traceability between some of the key requirements deliverables: use case models, user interface models, business rules, and user documentation. Use case models, which describe the functional requirements for your system, often refer to important business rules (such as needing a minimum balance of $500 in a bank account to earn interest). Therefore, you need to trace from the appropriate use case(s) to the appropriate business rules. Your use cases may also refer to items documented by your user interface model, such as specific screens and reports. Therefore, you will trace between these two deliverables. Your use cases, because they define the logic of how users interact with the system, will help drive the development of your user documentation. Therefore, you need to trace between these deliverables too. Your user documentation will refer to screens, so you’ll also trace from it into your user-interface model.

Now let’s consider what you need to trace between class models and other deliverables. Nonfunctional requirements, such as scalability and performance requirements, will be documented within your supplementary specifications and implemented by the classes of your system, hence the trace between these two deliverables. State chart models describe complex classes. In fact, you’ll often identify new attributes and operations as you model the various states of a class, both of which you need to trace back into your class model. Your class model should drive the development of your persistence model, so you’ll want to trace your class attributes to your tables’ columns (assuming a relational database on the backend) within your persistence model. Your systems source code is directly related to the classes defined by your class model, hence this trace. Finally, because I use class models to model the design of a component within a component model, there is traceability between these two deliverables as well.

Two deliverables worth noting are project plans and change cases, both of which trace to use cases. The RUP suggests that you develop your project plan based on your use case model. The basic logic is that since each project iteration should develop one or more use cases, you should start at your use case model to plan the iterations. The implication is that each iteration within your project plan will trace back to one or more use cases. You should trace change cases to the use cases that will likely be affected by those changes. Making these traces will help you determine the impact of these changes when necessary, and determine what portions of your design that you may want to rework now to support these potential changes.

Traceability and the RUP

An iterative and incremental approach to development, the industry norm and the approach RUPs promote, has several interesting implications for requirements traceability. When you take an iterative approach, it is important that you can trace easily between deliverables as they are being developed. Incremental development, where you build your system in portions, adds an additional twist to requirements traceability: you need to trace between versions of your deliverables as well. Before I begin, I need to point out a terminology issue. The RUP refers to an increment as an iteration. Yuck. The basic idea is that you iteratively develop an increment of your system, but for whatever reason, they chose to call this entire effort an iteration instead of an increment.

Figure 3 depicts the major deliverables of the RUP—the requirements model, the design model, the implementation model, and the test model—and the basic tracing issues between the versions of these models. Figure 3 was modified to fit the RUP terminology, from a similar diagram originally developed by John Nalbone of St. Louis-based Insight Technology Group. Note that each model shown in Figure 3, for the most part, is comprised of deliverables from the components of a test model. Because the design model for iteration n is developed based on both the requirements model of iteration n and the existing design model from iteration n-1, you need to trace it back to both of these models. This means your organization not only must have a handle on requirements traceability, it must also be proficient at configuration management to maintain traceability between model versions.

Figure 3

To maintain traceability between model versions, you need to baseline them, put them under configuration management, and forbid changes to the baselined version at the end of each iteration (you can, however, create a new version and update that). Remember that you are likely to have several iterations in each project phase, especially during the Construction phase, so a strategy for managing each iteration’s deliverables is crucial to your success. Because each iteration builds on the work of previous iterations and you are likely to refactor portions of your previous work to fulfill the requirements of your current iteration, you will find that you need to trace between versions of deliverables.

Who Should Trace Requirements?

Analysts who are responsible for gathering requirements must maintain traceability from their organization’s needs to their requirements model to the portions of the test model that verify the requirements and to the portions of the design model that show how those requirements will be mapped. Designers are responsible for determining how the requirements will be realized, so they need to work with the analysts to ensure traceability between their deliverables. Designers also work with architects to ensure traceability with your project architecture and with your programmers to ensure traceability from the design to the code. Your architecture team will work together to ensure that your project architecture traces to your enterprise architecture (assuming that your organization has one). Your test engineers will work with all project team members to guarantee traceability to the test model. It should be clear by now that everyone involved with your project is responsible for requirements traceability throughout the entire project life cycle.

Secrets of Success

Trace requirements continuously. To be successful, traceability should be a side effect of your daily work, not an afterthought. Remember, the benefits of requirements traceability are achieved throughout the entire project life cycle, so the sooner you record your traces, the sooner you’ll benefit.

Tool support is crucial. Due to the consistency of the object paradigm, and of the UML diagrams based on that paradigm, it’s reasonable to expect that much of your project’s traceability should be performed automatically. Unfortunately, this doesn’t appear to be the case, since few tools on the market support full traceability.

Understand why requirements traceability is important. If people don’t understand the bigger picture of why they need to trace, they’re unlikely to invest the effort required to perform requirements traceability. Share this article with them. Talk about it. Get them the training and education that they need to do their jobs. Find mentors that understand how to develop robust software to help educate your staff.

Have a traceability strategy. Your organization should define and document a requirements traceability strategy, communicate it to your staff, and actively support and enforce it on all software projects. Requirements traceability won’t happen by chance. You need to work the issue to be successful.

Use traceability to improve your productivity. Your goal isn’t to produce reams of documentation—it’s producing effective software. Organizations that use requirements traceability to improve their overall productivity find that developers are more than eager to trace requirements.

Requirements traceability is a crucial facet of software development whose benefits are often underestimated and sometimes misunderstood. Traceability is a key enabler of change control, the ability of your organization to manage the effects of changes in its environment and in its system requirements. An incremental and iterative approach to development, fundamental to the RUP and the object-oriented software process in general, definitely increases the complexity of requirements traceability. Traceability is hard, but that doesn’t mean you shouldn’t do it. My experience shows that a mature approach to requirements traceability is often a key distinguisher between organizations that are successful at developing software and those that aren’t. Choosing to succeed is often the most difficult choice you’ll ever make—choosing to trace requirements on your next software project is part of choosing to succeed.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.