Latest posts by Glennan Carnie (see all)
- The Rule of Zero - January 15, 2015
- The Rule of The Big Four (and a half) – Move Semantics and Resource Management - January 1, 2015
- The Rule of The Big Three (and a half) – Resource Management in C++ - December 18, 2014
RULE 7: Describe ALL the transactions
A use case, as the name implies, describes the usage of the system from the point of view of some beneficiary (our Actor). It is NOT (as I seem to spend my whole life telling people) is just the system function, organised as some sort of graphical ‘sub-routine’. This means the use case description must include the expected behaviour of the actors as well as the expected behaviour of the system.
This can sometimes appear counter-intuitive to use case newcomers. If the use cases define the functional behaviour of the system, then surely we can’t impose requirements on our users (the actors)?
In fact, this is not the case (and stop calling me Shirley).
The use case describes what we (or, more correctly, our customers) would like to happen when they use the system. It describes the typical interactions between stakeholder and system, such that the stakeholder achieves their goal. If the goal of the use case is beneficial to the stakeholder (see Rule 5) then the stakeholder has compelling reasons to behave as we describe in the use case. In other words, if the stakeholder wants the end result, they should comply with the behaviour described in the use case.
For example, if the system requests some information from the actor it is reasonable to expect them to respond with the information. In effect we are imposing requirements on the stakeholder (“when the system requests information, you shall respond”). Of course, there’s nothing to stop the obtuse user from not responding, walking away, or doing any number of other bizarre and inexplicable things; but these behaviours are a fantastic source of exceptional flows. This approach moves the use case writer away from describing system functions and instead focuses them on the transactions between the stakeholder and the system.
The use case description defines the system behaviour as a sequence of atomic transactions between the actors and the system. Atomic is used in the sense of indivisible. This means that, in the context of the problem domain the transaction cannot be broken down into smaller transactions. (See also: Rule 9). There are four basic transactions, and the use case description will be made up of sequences of these transactions:
- The actor supplies information to the system. Information could be an event (such as the trigger event) or data; or both.
- The system does some work. Remember to describe the results of the work, not how the result is achieved
- The system supplies information to the actor. Again, this could be requests for information, output signals, etc.
- The actor does some work. As mentioned above this is unenforceable, but reasonable behaviour on the part of the actor.
I suggest writing each transaction in a simple, semi-formal, declarative style. For transactions involving information exchange into or out of the system (that is, ‘Actor supplies information'; ‘The system supplies information to the actor’) I use the following style:
[Source] [Action] [Object] [Target]
For example: “The Navigator supplies the Airfield Altitude to the NAV/WAS system”
For descriptions of work being done (either by the system or by the actor) I use the following form:
[Subject] [Action] [Object] [Constraint]
For example: “The ARS rewinds the hose at 5 ft/s +/- 0.5 ft/s”
|Constraint:||5 ft/s +/-0.5 ft/s|
If a transaction contains more than 3 punctuation marks it’s probably too complicated and should be restructured to make its meaning better understood.
Weak phrases make for comfortable reading of a use case but are apt to cause uncertainty and leave room for multiple interpretations.
Use of phrases such as “adequate” and “as appropriate” indicate that what is required is either defined elsewhere or, worse, that the requirement is open to subjective interpretation. Phrases such as “but not limited to” and “as a minimum” suggest that the requirement hasn’t yet been fully defined.
Typical weak phrases include:
- As applicable
- As appropriate
- But not limited to…
The truth is, in general engineers have poor writing skills. By providing a framework for how use cases should be written you are limiting the scope for ambiguity, wooliness and inconsistency.