Key Principle
Adopting the statechart approach follows a disciplined sequence: requirements become screen rules, screen rules become high-level states, states become a statechart design validated by four structural tests, the design is captured in three specification artifacts, code is derived mechanically from the specification, and testing exploits the statechart's structure for systematic coverage. Each step feeds the next; skipping any reintroduces the ad-hoc construction the method exists to prevent.
Why This Matters
"Almost without exception, user interface software is coded without an overall software design" (Chapter 1). The industry-wide habit of jumping from requirements to code produces software that is "difficult to understand and enhance" (Chapter 1) and resists every subsequent modification. This playbook exists because knowing statechart notation is not the same as knowing how to apply it. "It is usually impossible to understand the required behaviour of a user interface and then immediately produce a statechart design for that interface" (Chapter 9). The steps below convert the inherently iterative design process into a repeatable workflow that eliminates the class of bugs where actions fire in the wrong context -- the mechanism behind the claimed 80-90% bug reduction.
The Seven Steps
Step 1: Requirements to Screen Rules (Temporary Artifacts)
Screen rules are a thinking tool, not a permanent specification. For every screen, catalog every UI item and how its behavior and appearance vary across contexts. The critical question for each item is not "what does it do?" but "when is it available, and how does its behaviour differ across contexts?" (Chapter 9). Catalog entry/exit conditions, modes (read-only vs. read-write), items with varying behavior (enabled/disabled, visible/invisible), and items with constant behavior -- which are "surprisingly few" (Chapter 9). Assuming constancy where variation exists causes states and transitions to be omitted from the model.
Step 2: Screen Rules to High-Level States (States-First Thinking)
Invert the natural instinct. Instead of asking "what action should this event trigger?", ask "in what state is this event meaningful?" "The designer first identifies the contexts (states) in which the events can occur and then the actions are identified for the events. Identifying the states first builds a solid framework on which events and actions can easily be added" (Chapter 9). Each screen or canvas becomes a top-level state. Subwindows get states placed according to calling scope: nest inside the parent if callable from only that screen; place at the top level if callable from multiple screens. This hierarchy placement encodes calling relationships and makes structural reachability errors visible before any code is written.
Step 3: States to Statechart Design (Hierarchy, Concurrency, History)
Arrange states in a hierarchy using depth for two purposes: refinement (top-down, delaying lower-level details) and clustering (bottom-up, reducing arrows). "Depth allows a state diagram to be viewed at different levels of abstraction. It provides an effective way of managing the design of a complex system" (Chapter 6). Consolidate items controlled by common events into the same concurrent region; separate truly independent behavior into different regions so that "parts of the design [can] be understood and modified in isolation from the other parts" (Chapter 9). Use history states to preserve context across suspensions and resumptions.
Step 4: Design Tests (Completeness, Reachability, Dead States, Determinism)
Apply four structural tests continuously during construction, not as a final gate. "It is not intended for the tests to be applied to a statechart when it is completed; they should be applied during the design process to avoid introducing problems" (Chapter 9).
- Completeness: For every state, verify every UI object's events are handled. An unhandled event means the corresponding control should be disabled.
- Reachability: Trace entry paths from the initial state to every state; verify default starts for concurrent parts and history mechanisms.
- Dead states: Cross-reference entry actions against exit conditions. A state that disables the only control capable of triggering its exit transition is dead.
- Determinism: Verify mutual exclusivity of guard conditions on same-event transitions. "If the same event with different conditions leaves a state, then only one of those conditions should evaluate to true at any given time" (Chapter 9).
Step 5: Three-Artifact Specification (Diagram + Event-Action Table + State-Item Table)
The finalized design is captured in three complementary artifacts. The statechart diagram shows flow structure visually. The event-action table records every transition's implementation detail: guard conditions, side-effect actions, and next state. The state-item table records every UI object's configuration in every state. "Statecharts should be the definitive specification of a user interface's behaviour" (Chapter 9). The diagram alone is an incomplete specification; the tables ensure full rigor while the diagram stays visually comprehensible. Once these three artifacts exist, screen rules are discarded.
Step 6: Coding (Control Objects, State Procedures, No Conditionals)
"Coding a statechart is a simple process that can be completed very quickly once the design has been finalized" (Chapter 13). The mapping is mechanical:
- One state variable per hierarchy level; one per concurrent region.
- Event handlers contain only a delegation call to the control object: "No other code is contained in the event handlers" (Chapter 13).
- Each state becomes a state procedure (
go_state_N) that sets UI attributes unconditionally: "State procedures always set the same attributes to the same values. In other words there should be no conditional statements which could cause different attributes to be set" (Chapter 13). If you need a conditional inside a state procedure, the statechart is missing states. - Keep code for the same event in different contexts separate even when actions are identical: "If the same event can occur in two different contexts and the resulting actions are identical, it is still strongly advised that the code for the two events are kept separate" (Chapter 13).
Step 7: Testing (White-Box via Multiple-Condition Coverage)
The statechart's explicit state model enables systematic white-box testing. Every state, transition, and guard condition is visible in the specification, so test cases can be derived mechanically to achieve multiple-condition coverage. This replaces trial-and-error testing where "Developing software by trial and error is not good" (Chapter 3).
Key Quotes
"The basic philosophy of the approach is to design the software so that it can be changed repeatedly throughout the lifetime of the system, rather than simply coding the software to behave in a particular way for the first release." -- Ian Horrocks, Chapter 1
"It is usually impossible to understand the required behaviour of a user interface and then immediately produce a statechart design for that interface." -- Ian Horrocks, Chapter 9
"Coding a statechart is a simple process that can be completed very quickly once the design has been finalized." -- Ian Horrocks, Chapter 13
"State procedures always set the same attributes to the same values. In other words there should be no conditional statements which could cause different attributes to be set." -- Ian Horrocks, Chapter 13
Rules of Thumb
- Never jump from requirements to code; the screen-rules step forces exhaustive discovery of behavioral variation before any state structure is committed
- Think in states first, events second: enumerate contexts before attaching actions
- Hierarchy serves two purposes (refinement and clustering); recognize which one applies to avoid misstructured nesting
- Apply design tests continuously during construction, not as a final quality gate
- A conditional inside a state procedure signals a missing state in the statechart -- fix the design, not the code
- Keep event handling code separate across contexts even when behavior is identical; minor duplication is cheap, cross-context side-effects are expensive
- The three-artifact specification is the definitive specification; screen rules are scaffolding
- Architecture without a design notation is reorganization, not solution -- control objects will accumulate the same tangles that plagued event handlers
Related References
core-framework.md-- Event-state-action paradigm and design-before-code philosophy (Steps 1-2)design-heuristics.md-- States-first thinking, screen rules, and design tests (Steps 2, 4)statechart-notation.md-- Hierarchy, concurrency, and history notation (Step 3)three-artifact-specification.md-- Diagram, event-action table, state-item table (Step 5)coding-statecharts.md-- Control objects, state procedures, no-conditionals rule (Step 6)ucm-architecture.md-- Three-layer separation underpinning control objects (Step 6)