Top 10 modeling hints for system engineers: #7 Requirements models help you avoid early expensive defects

Bruce Douglass shows you how to make requirements that are more complete, more correct, more precise, and more accurate.


Bruce Douglass (, Rational Chief Evangelist, Systems Engineering, IBM

author photoEmbedded Software Methodologist. Triathlete. Systems engineer. Contributor to UML and SysML specifications. Writer. Black Belt. Neuroscientist. Classical guitarist. High school dropout. Bruce Powel Douglass, who has a doctorate in neurocybernetics from the USD Medical School, has over 35 years of experience developing safety-critical real-time applications in a variety of hard real-time environments. He is the author of more than 5,700 book pages from a number of technical books including Real-Time UML, Real-Time UML Workshop for Embedded Systems, Real-Time Design Patterns, Doing Hard Time, Real-Time Agility, and Design Patterns for Embedded Systems in C. He is the Chief Evangelist at IBM Rational, where he is a thought leader in the systems space. Bruce consults with and mentors IBM customers all over the world. Follow Bruce on Twitter @BruceDouglass.

05 November 2013

Also available in Chinese Russian Japanese

Doing a good job of creating requirements specifications is harder than it looks. So hard, in fact, that in over 35 years, I've yet to see one that was free from defects. Requirements specifications are typically textual documents using "shall" statements. There are a number of fundamental problems with this.

First, text, while wonderfully expressive, is ambiguous and subject to multiple interpretations. It is very difficult to be precise with natural language. This makes natural language a good fit for poetry, but a less good fit for technical specification.

Note: I have actually written poetry using UML state machines, but it has proven to be, let us say, not a preferred choice.

Furthermore, it is difficult to ensure that the specification is complete and you haven't missed anything. Have you covered all the cases, situations and, environments in which the system must operate? What about all performance and other quality of service requirements? With all fault and exception conditions?

It is even more difficult to demonstrate the consistency of a large number of requirements. In a specification of hundreds of pages, consistency is a thorny problem.

How are such specifications usually verified before handing them off to engineering teams for design and development? Most commonly, either they are not (this results in long system verification and validation cycles as issues are worked through at the end of the project), or by mind-numbing hours of peer review.

The problem is that requirements-as-text is not inherently verifiable. The solution is to create requirements-as-models.

Consider a simple use case "Evening Low Volume Mode" for a traffic light control system. The primary through traffic lights flash yellow and the secondary road through traffic flashes red. Figure 1 shows how such a simple set of requirements can be cast as an executable state machine, sending messages to the actors in its environment, primary road pedestrians (PP), secondary road pedestrians (SP), primary through traffc vehicles (PV), primary turn traffic vehicles (PtV), secondary through traffic vehicles (SV) and secondary turn traffic vehicles (StV). The figure also shows how to add trace links to the state machine elements to show what requirements are represented.

Figure 1. Simple use case state machine for “evening low volume mode”
use case state machine

The primary advantage of this model is that it is executable. It can be used to explore different situations, context, values, and the order of arriving events. Of course the state machine in Figure 1 is almost trivially simple. Consider, however, a slightly more complex set of requirements for "fixed cycle mode" for the same traffic light control system:

  • Use Case: Fixed cycle mode
    • Intersection contains a primary road and secondary road
    • Each road has through lanes and left turn lanes
    • Through lanes, for both directions on the same road, are activated simultaneously
    • Turn lanes, for both directions on the same road, are activated simultaneously
    • Through lanes are activated without outside stimulus through a RED-GREEN-YELLOW-RED cycle. The other road lights are held at RED (and DON'T WALK) while a road permits traffic
    • Turn lanes are activated by the arrival of a car in the turn lane; otherwise they remain RED
      • The next time that through road lane would normally be active, the turn lane goes first with the through lane remaining RED until the turn cycle is complete
      • Both opposing turn lanes cycle RED-GREEN-YELLOW-RED. After that the through lanes are permitted to cycle to green
      • Once a turn lane has been "handled" another arrival is necessary to activate it again
    • Pedestrian lights remain DON'T WALK unless activated by a pedestrian arrival button press
      • The next time that the through lane goes green, the road pedestrian line cycles through:
        • DON'T WALK
        • WALK
        • DON'T WALK
      • The through lane shall cycle to yellow only after the pedestrian light becomes DON'T WALK

This is not a hugely complex use case, but many different scenarios of interest with different combinations of cars in through lanes, turn lanes, and pedestrians can be constructed. The state machine for this use case, shown in Figure 2, is less trivial and less obvious. All interesting circumstances and scenarios are accounted for. Execution of this model allows you to explore different combinations of events, conditions, and values to ensure that the system is correct all the time.

Figure 2. Use case state machine for "fixed cycle mode"
use case state machine

As a normal consequence of such use case functional analysis, missing requirements are identified. They are then added to the textual specification and linked to the model specification elements. This results in better requirements; requirements that are more complete, more correct, more precise, and more accurate.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=Top 10 modeling hints for system engineers: #7 Requirements models help you avoid early expensive defects