You are currently browsing the Sticky Bits blog archives for November, 2010.

The Baker’s Dozen of Use Cases

November 22nd, 2010

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:

  1. The actor supplies information to the system. Information could be an event (such as the trigger event) or data; or both.
  2. The system does some work. Remember to describe the results of the work, not how the result is achieved
  3. The system supplies information to the actor. Again, this could be requests for information, output signals, etc.
  4. The actor does some work. As mentioned above this is unenforceable, but reasonable behaviour on the part of the actor.

The fundamental transactions of a use case



Writing style

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”

Source: The Navigator
Action: Supplies
Object: Airfield Altitude
Target: 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”

Subject: The ARS
Action: Rewinds
Object: The Hose
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
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…
  • Effective
  • Normal
  • Timely
  • Minimize
  • Maximize
  • Rapid
  • User-friendly
  • Easy
  • Sufficient
  • Adequate
  • Quick

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.



<<Prev     Next>>

Importing IAR EW 5.4 Projects into Parasoft C++test

November 17th, 2010

Background

Recently I have been experimenting with Parasoft’s C++test tool for static analysis of C and C++ code. As part of this I went through the process of importing an existing C project developed in IAR’s Embedded Workbench toolset. Even though importing a project and checking it against MISRA-C isn’t too taxing, I though I would share my notes for doing this.

Read more »

The Baker’s Dozen of Use Cases

November 15th, 2010

RULE 6: If it’s not on the Context or Domain models, you can’t talk about it

(If you haven’t already read it, I’d suggest having a quick look over Part 1 of the Baker’s Dozen to familiarise yourself with the fundamentals of use case descriptions.)

Engineers love to solve problems. It’s what they do. A use case model though is not a design model – it’s an analysis model. Use cases describe what the system should do, and in what order. What use cases shouldn’t do is say how the system should achieve these things. That’s what design is for.

Stopping analysts (particularly if they’re developers) from writing implementation details in the use case descriptions is difficult.   One safe way of doing this is to limit the concepts written in the use case descriptions to only those defined on the Context or Domain models.

Both the Context model and Domain model describe things beyond the scope of software implementation. That is, they describe the problem domain, not the solution (software) domain.

The Context model defines the physical parts of the system – external systems, users, interfaces, communication channels, etc.

The Domain model describes the informational context of the system – what artefacts exist, are produced, are inputs or outputs; and how these elements relate to each other.

(See Rule 4 for more on these models; and more.)

All the data in these two models will exist irrespective of what software solution is developed. If they change then our understanding of the problem has changed.

When reviewing use cases look for concepts that are not defined on the Domain or Context models. These concepts are very likely to be implementation details. Look for items like ‘database’, ‘Hardware Abstraction Layer’, ‘Observer’, ‘RTOS’, etc. These are an indication your requirements are actually describing the solution rather than the problem.




<<Prev     Next>>

The Baker’s Dozen of Use Cases

November 8th, 2010

RULE 5: Focus on goals, not behaviour

There is a subtle distinction between the functional behaviour of the system and the goals of the actors.   This can cause confusion: after all, the functional behaviour of the system must surely be the goal of the actor?
It is very common, then, for engineers to write use cases that define, and then describe, all the functions of the system.  It is very tempting to simply re-organise the software requirements into functional areas, each one becoming a ‘use case’.  Paying lip-service to the ‘rules’ of use case modelling, these functions are organised by an actor that triggers the behaviour.

Use Cases based on functional requirements, rather than Actor goals.

I call these entities Design Cases to distinguish them from use cases; and they can be the first steps on the slippery slope of functional decomposition (see Rule 11 for more on this)

Identifying goals requires a change in mindset for the engineer.  Instead of asking “What functions must the system perform?” and listing the resulting functionality, ask: “If the system provides this result, will this help the actor fulfil one (or more) of their responsibilities”. If the answer to this question is ‘yes’ you’ve probably got a viable use case; if the answer’s ‘no’, or you can’t answer the question then you probably haven’t fully understood your stakeholders or their responsibilities.

In other words, the focus should be on the post-conditions of the use case – the state the system will be in after the use case has completed.  If the post-condition state of the system can provide measurable benefit to the Actor then it is a valid use case.

Let’s take a look at what I consider a better Use Case model:

Organising use cases by Actor Goal

The post-conditions of the use cases (above) relate to the goals of the Actor (in this case an Air-Traffic Control Officer).  We can validate whether the post-conditions will be of value to the Actor.

The (main success) post-condition of Land Aircraft is that one of the ATCO’s list of aircraft (that he is responsible for) is on the ground (safely, we assume!).  At this point the aircraft is no longer the responsibility of the ATCO – one less thing for them to worry about.  I argue that this is a condition that is of benefit to the ATCO.

Similarly with Hand-off Aircraft.  As aircraft reach the limit of the local Air Traffic Control (ATC) centre they are ‘handed-off’ to another ATC centre; often a major routing centre.  The post-condition for the hand-off will be that the departing aircraft will be (safely!) under the control of the other ATC, and removed from the local ATCO’s set of aircraft he is responsible for.

Receive Aircraft is the opposite side of Hand-Off Aircraft.  That is, what happens when the ATCO has an aircraft handed over to them from another ATC region.  At the end of the use case, the ATCO must have complete details and control of the received aircraft.

When an aircraft takes off, the aircraft must be assigned to an ATCO, who is responsible for routing it safely out of the local ATC region.  The post-condition of Take-Off Aircraft must be that the aircraft is assigned to an ATCO and that ATCO has all required details of the aircraft’s journey.

In the last two use cases, the ATCO actually gains work to do (another extra aircraft to monitor).  The requirements of the system must ensure that when the new aircraft is received the transfer is performed as simply, or consistently, or straightforwardly, as possible.  This is the benefit to the Actor.

While one could easily argue this is a simplistic model for Air Traffic Control it demonstrates basing use cases on goals rather than functional behaviours.  Each use case is validated by its post-conditions, rather than its pre-conditions and behaviour.




<<Prev     Next>>

%d bloggers like this: