The Core Framework: Design Before Code with Statecharts

Key Principle

UI software is, almost without exception, built without an overall software design -- and this missing design phase, not the complexity of widgets or frameworks, is the root cause of UI code that is hard to understand, test, enhance, and maintain. The corrective is a three-part framework: adopt the event-state-action paradigm, structure the application using UCM (User Interface-Control-Model) architecture, and specify control behavior with statecharts. Design must precede code.

Why This Matters

The software industry normalized skipping the design phase for UI software. Development tools made initial coding fast, creating the illusion that UI software is easy to build. This perceived ease eliminated the felt need for design, producing code with "an intricate structure that is difficult to understand and enhance" (Chapter 1). The cost is enormous: "It is common for more than half the budget of a client-server project to be spent on the development and maintenance of the user interface" (Chapter 2).

The problem compounds over time. UI software lives through many modification cycles driven by user feedback, requirement changes, and iterative design. Each enhancement adds conditional branches and shared-state dependencies with no structural mechanism to prevent accumulation. Quality degrades with every release -- not because developers are unskilled, but because the construction approach itself is structurally incapable of absorbing change. The five recurring symptoms of conventionally-built UI code are: difficult to understand, difficult to test systematically, contains bugs even after extensive testing, difficult to enhance without side-effects, and deteriorating quality over successive enhancements (Chapter 3). These are structural consequences of the paradigm, not failures of individual discipline.

The book's design philosophy optimizes for changeability across the system's lifetime, not first-release correctness. Direct manipulation UIs are "intrinsically far more complicated than command line interfaces because a user can have several partially completed dialogues that can be suspended and resumed at any time" (Chapter 2). The developer must track all interaction threads simultaneously and ensure no combination of user actions produces an invalid state. This concurrent dialogue problem is the specific challenge that demands a design discipline.

Good Examples

• The event-state-action paradigm: When a user event arrives, the system's current explicit state determines which actions execute and what state follows. The developer ensures "a user can only supply valid events at any given time" (Chapter 4) by disabling or hiding controls invalid in the current state. This replaces scattered conditional logic with a tractable, reviewable model. The paradigm is "not a theory of how user interface software could be constructed. It is the nature of all direct manipulation user interfaces" (Chapter 4) -- states already exist in bottom-up code, scattered across global variables and conditional checks. The only question is whether they are made explicit.

• UCM three-layer separation: UI objects become thin pass-throughs that forward messages to control objects. Control objects maintain explicit state and determine actions based on the message plus their current state. Model objects handle persistent data. The key constraint: UI objects never access model objects directly; model objects never message UI objects. The control layer mediates all communication. This centralizes coordination logic so that behavior is explicit and locatable rather than scattered across event handlers.

• States as accumulated history: A word processor's close event must know whether the document was opened-from-file vs. created-new, and whether it has been modified since last save. "This information cannot be determined retrospectively; the information must be stored when these events occur" (Chapter 3). Statechart states encode this history explicitly, so transition logic never needs to reconstruct what happened before.

Counterpoints

• The event-action paradigm (the core anti-pattern): Most developers carry the mental model that an event alone determines which actions execute. "Despite the wide acceptance of the event-action paradigm, it does not reflect the reality of user interface construction. The paradigm is too simple. It is based on the assumption that user interface objects act independently of each other" (Chapter 3). It ignores three critical factors: cross-object state (opening a file enables formatting tools), interaction history (closing requires knowing whether the document was opened vs. created), and domain data values (send-reminder is only valid when a bill is unpaid and overdue). The correct response is always a function of (event, state, object states, data values) -- never of event alone.

• Bottom-up construction: Without a design step, developers build each event handler independently, then patch in coordination when they discover interdependence. "Individual event handlers are not written in their entirety at one time... Instead, the code in event handlers are usually built up gradually until a co-ordinated group of event handlers is achieved" (Chapter 3). The result: coordination logic scattered across handlers, implicit coupling through shared variables, and no single artifact describing overall behavior. Even a ~100-line calculator exhibits this -- "a bottom-up approach to constructing user interface software is not a scalable approach" (Chapter 3).

• Shared mutable state as coordination mechanism: In the calculator example, a single DecimalFlag variable was accessed by six of seven event handlers. "The code that makes the objects work together is distributed throughout the event handlers" (Chapter 4), making the system impossible to reason about as a whole. "It is like constructing a building without solid foundations" (Chapter 4).

Key Quotes

"Almost without exception, user interface software is coded without an overall software design. In this respect, user interface software is unique. No other type of software is constructed without there being at least some initial design work." — Ian Horrocks, Chapter 1

"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

"Despite the wide acceptance of the event-action paradigm, it does not reflect the reality of user interface construction. The paradigm is too simple." — Ian Horrocks, Chapter 3

"This is not a theory of how user interface software could be constructed. It is the nature of all direct manipulation user interfaces." — Ian Horrocks, Chapter 4

Rules of Thumb

• If you cannot describe the system's intended behavior in a single reviewable artifact before writing code, you are doing bottom-up construction
• The correct response to a user event is always a function of (event, current state, object states, data values) -- never of event alone
• Context cannot be determined retrospectively; state must be recorded when events occur, not reconstructed at decision time
• Architecture without a design notation (UCM without statecharts) is reorganization, not solution -- control objects will accumulate the same tangles that plagued event handlers
• State explosion is a notation problem (flat state transition diagrams), not a paradigm problem; hierarchy and concurrency in statecharts resolve it
• If peripheral functions (cancel, undo, edge-case operations) are bug-prone, suspect a missing explicit state model -- these operations fail first in bottom-up code because no constraints define when they are valid

Related References

• (No other reference files currently exist; links to be added as the reference set grows)