Sticky Bits

Interfaces

One of our key design goals is to reduce coupling between objects and classes. By keeping coupling to a minimum a design is more resilient to change imposed by new feature requests or missing requirements[1].

An Interface represents an abstract service. That is, it is the specification of a set of behaviours (operations) that represent a problem that needs to be solved.

An Interface is more than a set of cohesive operations. The Interface can be thought of as a contract between two objects – the client of the interface and the provider of the interface implementation.

The implementer of the Interface guarantees to fulfil the specifications of the Interface. That is, given that operation pre-conditions are met the implementer will fulfil any behavioural requirements, post-conditions, invariants and quality-of-services requirements.

From the client’s perspective it must conform to the operation specifications and fulfil any pre-conditions required by the Interface. Failure to comply on either side may cause a failure of the software.

Read more »

Use cases have become a core part of the requirements analyst’s arsenal.  Used well they can bring dramatic increases in customer satisfaction and a whole host of other subtle benefits to software development.

The use case itself is very simple in concept: describe the functionality of the system in terms of interactions between the system and its external interactors.  The focus of the use case is system usage,  from an external perspective.

Despite this apparent simplicity, requirements analysts frequently struggle to write coherent, consistent use cases that can be used to facilitate development.   Often, the use case analysis becomes an exercise in confusion, incomprehension and the dreaded ‘analysis paralysis’.

This article aims to aid use case writers by presenting a set of rules to follow when performing use case analysis.  The rules are designed to avoid common pitfalls in the analysis process and lead to a much more coherent set of requirements.

A brief introduction to use cases

The Baker’s Dozen ‘rules’:

Rule 1: Use cases aren’t silver bullets

Rule 2: Understand your stakeholders

Rule 3: Never mix your actors

Rule 4: The "Famous Five" of requirements modelling

Rule 5: Focus on goals, not behaviour

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

Rule 7: Describe ALL the transactions

Rule 8: Don’t describe the user interface

Rule 9: Build yourself a data dictionary

Rule 10: The magical number seven (plus or minus two)

Rule 11: Don’t abuse <<include>>

Rule 12: Avoid variations on a theme

Rule 13: Say it with more than words

 

These 13 guidelines are by no means exhaustive (for example, what about ‘Abstract’ actors; or System Integrity use cases?) and I’m sure there are dozens more I could add to the list (by all means, let me know your golden rules)  The aim of writing this article was to give beginners to use case modelling a simple framework for creating useful, effective use cases – something I think is sorely missing.

The Baker’s Dozen can be (neatly) summed up by the following principles:

• Understand the difference between analysis and design.
• Understand the value of a model – know why to create the model, not just how.
• Understand the difference between precision and detail.
• Keep it simple; but never simplistic

Next>>

Rule 13: Say it with more than words

Use case descriptions are most commonly written in text format (albeit often a stylised, semi-formal style of writing). Text is a very effective method of describing the transactional behaviour of use cases – it’s readily understandable without special training; most engineers can produce it (although the ability to write basic prose does seem beyond the capability of many!); and it is flexible enough to deal with complex behaviours – for example, variable numbers of iterations through a loop – without becoming cumbersome.

 

Use the most appropriate notation for the behaviour you are describing

 

However, this flexibility can come at the price of precision. Sometimes, for example in many control systems, you have to state precisely what the response of the system will be. Words, in this case, are not adequate (that said, I have seen requirements engineers attempt to describe the overshoot behaviour of a closed loop control system in English prose!)

This rule therefore should be: find the most appropriate notation to describe the transactions between the actors and the system; with a corollary that sometimes the right notation is multiple notations. Use tables, charts, diagrams, activity diagrams, flowcharts, mathematical models, state charts, or combinations of these, to describe the behaviour. Don’t get caught up in the dogma of use cases that says the use case description must be text. For most systems I have found that combinations of methods work best – some transactions are best described using semi-formal text; some by state machines; others by tables. The skill is recognising the type of transactions you are describing and picking the appropriate method.

 

<<Prev     Home>>

Rule 12: Avoid variations on a theme

A common affliction amongst novice use case modellers (particularly those from a development background) is the desire to fettle the use case model – to organise it, revise it, balance it; and generally make it look more like a design model.  Unfortunately, beyond a certain point this effort actually starts to degrade the utility and effectiveness of the model.  More and more effort is put into a model that becomes less and less useful to the customer and the analyst.

This all-too-common situation is known as ‘Analysis Paralysis’.

I always advise, unless you can provide a really compelling reason to do otherwise avoid associations between use cases.  Yes, you might have a less optimal model, but at least your stakeholders will find it easy (or easier) to follow.  This is price you always pay with use case associations: Elegant but complicated to understand, versus sub-optimal but explicit.  In my view explicit always wins; after all, we’re trying to understand the problem, not design a solution.

Case in point:  Use case specialisation.

In UML a use case (and indeed an actor) is a special form of classifier. One of the properties of classifiers is that they can be specialised – that is, a new classifier may be defined that has the properties and behaviours of the parent, but may extend or modify these attributes. The definition of the specialised classifier is that it is also a the type of its parent – that is, all instances of the specialised classifier form a subset of the set of parent classifiers.

 

Use case and actor specialisation

In use case terms it means we can define actors or use cases that represent specialisations of some base behaviour.  As part of our analysis we may choose to define actors whose goals form a superset of another actor’s. For example, we could define an Administrator actor as a specialisation of a User actor. The Administrator performs all the functions of the User but has additional behaviours (admin tasks)

Actor specialisation is avoidable if you consider actors as roles. A role is just a set of competencies and behaviours that can be adopted by a person (when interacting with the system). So, when I perform everyday tasks I adopt the role of a User actor; when I need to do an administrative task I adopt the role of an Administrator (if I’m able) This model also means I can be an Administrator without being a User – something the specialisation model doesn’t allow.

For use cases the problem becomes more complex. Given any particular use case, what does it mean to specialise it?  A specialised use case is like a base use case, but may have different behaviour. This complication is adding nothing to our comprehension of the system (in fact, possibly the opposite!).  Not to mention the pain you will go through trying to explain all this to your customers!

The Liskow Substitutabiliy Principle (LSP) can help with this situation.  In simple terms the LSP says that a derived class can be substituted for a base class object if, and only if, the derived class has no stronger pre-conditions (demands no more of the client) and has no weaker post-conditions (delivers no less). 

For use cases, this means the specialised use case must have the same pre-conditions as the super use case (or possibly weaker).  The specialised use case may override super use case functionality (whatever that actually implies!).  Finally, none of the scenarios in the specialised use case must result in weaker post-conditions than the super use case. 

This could be achieved by having a super use case with limited (or no) behaviour, strong pre-conditions and very weak post-conditions.

However, one could reasonably argue this super use case becomes little more than a generic place-holder and doesn’t really add much to our understanding of the system’s (transactional) behaviour.

Use case specialisation can be avoided very simply by forking the use case with an optional flow. For one variation take one path through the use case; for another variation take the other. Unfortunately, this causes the use case to become more complicated; but at the benefit of explicitness.

There are some rare cases where use case specialisation can be more explicit but these are more the exception than the rule.

 

<<Prev     Next>>

Rule 11 – Don’t abuse «include»

A use case contains all the steps (transactions) needed to describe how the actor (our stakeholder) achieves their goal (or doesn’t; depending on the particular conditions of the scenario). Therefore a use case is a stand-alone entity – it encapsulates all the behaviour necessary to describe all the possible scenarios connected to achieving a particular end result. That’s what makes use cases such a powerful analysis tool – they give the system’s requirements context.  Use case are also an extremely useful project management tool. By implementing a single use case you can deliver something complete, and of value, to the customer. The system may do nothing else, but at least the customer can solve one problem with it.

Occasionally, two use cases contain a sequence of transactions common to both sets of scenarios. This sequence may not necessarily occur at the same point in each use case (for example, the beginning) but will always be in the same order.

 

UML provides a mechanism for extracting this common information into its own use case. The mechanism is called the «include» relationship. The semantics of the «include» relationship mean that the base use cases are only complete if they fully, and completely, contain the contents of the included use case.

Included use cases (if you must use them)

This relationship can sometimes be useful, particularly if a sequence of transactions is repeated many times.

However, misunderstanding of «include» tends to lead to a very common abuse: functional decomposition of use cases.

Many use case modellers use the «include» relationship to split a complex use case into a number of smaller, simpler use cases. This can lead, in extreme cases, to an explosion of use cases, with leaf-node use cases capturing trivial functional requirements (for example “Capture button press”).  

These trivial use cases often have no meaning to stakeholders, who should be focussed on what they want to happen, rather than how it happens.  Also, there is a huge overhead is creating, reviewing and maintaining this vast number of use cases.

I call this approach “Design Cases” to differentiate it from a use case.

 

Design cases in action

Rather worryingly, several organisations actively promote Design Cases for requirements analysis.  The appeal is obvious:  functional decomposition is a familiar concept with most developers (and if it isn’t they really shouldn’t be developing software!); and it allows the developer to settle back into the comfortable territory of solving problems (rather than defining them)

Remember, use cases are an analysis tool for understanding the system. A simple, coherent set of use cases, reflecting the usage of the system from the customer’s perspective is far more effective than demonstrating, to the n-th level, how the system will operate. That’s what design verification is for.

My advice is to avoid «include» wherever possible.  Prefer repetition of text within the use case description, over trying to identify and extract commonality.  In this way each use case remains separate and complete; and there is no temptation to fall into the functional decomposition trap.  That way lies madness (or at least analysis paralysis).

 

<<Prev     Next>>

Rule 10:  The magical number seven (plus or minus two)

Psychologist George Miller, in his seminal 1956 paper "The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information", identified a limit on the capacity of human working memory. He found that adults have the capability to hold between five and nine ‘chunks’ of information at any one time. A ‘chunk’ may be a number, letter, word or some other cohesive set of data.

What has this to do with use cases? One of the primary functions of writing use cases is requirements validation – that is, are we actually building the correct system? The use case model is a technique for presenting the system requirements such that the customer can say either yes, we have a correct understanding of how the system should work; or no, we have misunderstood the system.

When presenting information to our (probably non-technical) customer it makes sense to keep the information content manageable. Try to keep the number of transactions in any one flow (that is, a sequence of use case steps between a trigger event and a conclusion) to between five and nine. This gives your customers the best chance of comprehending what you’re writing.

This means that the use case stops being a list of all the system requirements and becomes a précis of the system requirements. Each transaction may therefore equate to more than one system requirement. In practice this is not as over-simplifying as it sounds: requirements are often ‘clustered’ around elements of data and their production and manipulation – effectively what each use case transaction describes.

The skill in writing good use cases is the ability to précis requirements together to minimise the number of use case steps, without creating simplistic use cases.

The ‘seven, plus or minus two’ rule is not hard and fast; more a guideline. If your description has ten steps, this is not a problem; however, if it has thirty then there’s a chance you’ve over-complicated the step. The same is true at the other limit: three steps is fine; one step means you may have over-simplified and lost detail.

 

<<Prev     Next>>

Rule 9 – Build yourself a Data Dictionary

Transactions between the actors and the system typically involve the transfer of data.  This data has to be defined somewhere.  If you’ve built a Domain Model ( see Part 5 – here) most of the data will be identified there; but even then the class diagram is not always the most practical place to capture the sort of information you need to record.

Another way to capture this information is in a Data Dictionary.  A data dictionary defines each piece of data in the system, and attributes about that data.  Typically, a data dictionary holds (but is not limited to) the following:

• An Identifier.  This is how the data will be referred to.  Remember to use a term that has meaning in the problem domain.
• Definition.  What does this data represent?  (And remember: a good definition consists of a genus – what type of thing I’m defining – and a description)
• Units of measure; if applicable
• Valid range; again, if applicable
• Resolution.  That is, what’s the smallest difference I can measure?  This can become important if your implementation may use fixed point number schemes (for example).

This information is all vital to the developers who must design and code interfaces, etc. but it also has benefit when writing use case descriptions – it decouples the behaviour of the system from its data.

Just as we should decouple user interface details from the use case description (see Rule 8) so should we decouple the data transactions.  Describing the data requirements of a transaction in the use case description is cumbersome and leads to a potential maintenance problem (what if the resolution of a data item changes?  Or its units of measure?  Ask the team that developed the flight systems software of the Mars Climate Orbiter about getting units of measure confused!)

As you define your data dictionary, you can refer to data items (by their name) in the use case text.  Use some typographical convention (I use italics) to identify a data item from the data dictionary; or, you could hyperlink it. 

If the data requirements change you shouldn’t need to change the use case – unless it leads to a change in behaviour.  Similarly, you don’t need to elaborately detail exception flows for invalid data.  The data dictionary defines what is valid; the use case defines what should happen if we receive invalid data.  A simple, clear separation of responsibilities.
 
The Data Dictionary is not a new idea.  Twenty years ago, when I started developing software, a Data Dictionary was always created, and was considered a vital part of the design.  Unfortunately, it seems to have gone out of fashion, or been forgotten, in many software development circles.

 

<<Prev     Next>>

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.

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>>

RULE 4 : The “Famous Five” of requirements modelling

As I discussed in Rule 1, a common misunderstanding of use cases is that they are the software requirements. Unfortunately, this isn’t the situation. Use cases are merely an analysis tool – albeit a very powerful tool (when used in the right situation).

Use cases are just one technique for understanding and analysing the requirements. In order to fully understand the requirements our use cases are going to need some support. Use cases are just one of my “Famous Five” of requirements analysis models.

The Requirements models are:

• The Use Case model
• The System Modes model
• The Context model
• The Domain model
• The Behaviour model

Why five models? Well, each one tells me about a different aspect of the system. No one point of view can tell me everything I need to know in order to ensure my requirements are coherent, consistent and unambiguous.


The Use Case model is focussed on interaction behaviour: the who, how, what and when of interaction between the stakeholders and the system.
Use cases focus on operational scenarios. For some systems (especially a lot of application software) the (transactional) exchange of information between the users, or other direct interactors, and the system forms the bulk of the software functional requirements.
However, many embedded systems are not user-centric, or transactional in their behaviour (for example, a closed-loop control mechanism). Anyone who has attempted use case analysis on such systems tends to find the use case model is non-intuitive to construct; and tends not to yield very much information about the behaviour of the software.

The System Modes model defines the temporal behaviour of the system. That is, how the behaviour of the system changes of time, in response to external (and internal) stimuli.
The System Modes model allows the analyst to capture when and how the system functionality is available. The System Modes model is a declarative diagram, showing the behavioural modes of the system (without saying how the behaviour will be enacted) and the signals or events that cause the behaviour to change.
Application software may not be modal: it’s either running or it’s not. Embedded systems tend to have more complex dynamics (I see the system dynamics as one of the big differentiators between embedded software and application software). There are typically states where the system’s primary functionality is available, and other states where it is not. For example, most embedded systems cannot provide their primary functionality when they are starting up, or shutting down, or in a maintenance mode.

The Context model defines the physical scope of the system: what is part of the system (under your control) and what is external to the system.
When creating requirements it is vital to separate the Problem Domain (the part of the real world where the computer is to exert effects) from the Solution Domain (the computer and its software). In fact, requirements should be describe in terms of the effects the system should exert in the Problem Domain (rather than how it should be designed). In addition there must be specifications for what are called Connecting Domains – that is, how the system’s input/output devices must behave (interface specifications).
The Context model gives a clear visual delineation of the Problem Domain (the environment), the Solution Domain and the Connecting Domains. The software is treated as a single black-box entity. The environment consists of the Direct Interactor stakeholders. Each Stakeholder interacts with the system via one or more interfaces (often called Terminators). For each element on the Context model there should be a set of requirements. In this example I have simulated a Context Model using a SysML Internal Block diagram.

The Domain model focuses on the information (that is, data) in the system and, more importantly, the relationship between the information.
The domain model aids with building a project ‘glossary’. In any project there is a huge amount of tacit information about how the problem domain operates, and the language that is used to describe it.
The focus of the Domain model is understanding the problem and describing it, rather than specifying the problem’s solution. Typically, a form of entity-relationship diagram is used. With UML, a class diagram is used (or a Block Definition Diagram in SysML).
It is tempting for development teams to skip this stage; the argument being “well, everybody knows this!” By actively and coherently modelling this information you may well avoid implicit misunderstandings; that can cost a project dear, if found too late.

The Behavioural model captures the transformational aspects of the problem. The Behavioural model focuses on sources and sinks of information, and what transformations are performed by the system in between.
Although ultimately all software behaviour comes down to executing imperative code, this should be avoided for requirements analysis. Rather, focus on declarative statements of behaviour and where the data comes from (and goes to) rather than how the algorithms will be implemented.




The great strength of producing multiple models of the same system is that they are self-validating. Building a consistent set of models gives confidence that the analyst has truly understood the problem.
Concepts defined in one model must not conflict with the same concept in another model. For example, stakeholders defined in the Use Case model (its actors) must also appear on the Context model (otherwise, how are they interfacing to the system?!); similarly, the Use Case model should not mention any data or information that is not captured on the Domain model.
As I wrote in Rule 1, systems tend to have a predominant characteristic – that is, they will either be a Modal problem, a Transactional problem, a Flow-of-materials problem or a Data-Driven problem. When you are building your models of the system one or two diagrams will tend to give you more information than any of the others. For example, in a data-driven problem the Domain model will probably give you more information about the behaviour of the system than, say, the Modes model or Use Case model. The table below gives an indication of the relative value of each of the models.

<<Prev     Next>>

RULE 3: Never mix your Actors

The UML definition of an Actor is an external entity that interacts with the system under development. In other words: it’s a stakeholder.

Having analysed all your stakeholders (see Part 3 ) it’s tempting to stick them (no pun intended) as actors on a use case diagram and start defining use cases for each.

Each set of stakeholders (Users, Beneficiaries or Constrainers) has its own set of concerns, language and concepts:

Concerns.
Each stakeholder group has a different set of issues, problems, wants and desires. For example, Users are interested in functionality; Constrainers in compliance.

Concepts.
The way a system is perceived by the stakeholders depends on their viewpoint, their needs, their technical background, etc. Each group’s paradigm – their way of perceiving the system – will be different and involve often subtly different concepts. For example, Users may have no concept of return-on-investment (RoI) for the system; whereas this may be a key concept to a Beneficiary.

Language.
Just as concepts are different; so is the language used to describe them. In many cases, the same word is used in different contexts to mean different things. For example: how many different concepts of ‘power’ can you think of? Mechanical, physical, electrical, political…

It is vital never to mix actors from different stakeholder groups on the same use case diagram. Trying to mix actors leads to ambiguity and confusion; both for the writer and reader! The differences in concept, viewpoint and language will make the use case almost impossible to decipher and understand.

By all means draw a separate use case diagram for each set of stakeholders. (Note: non-User stakeholder use case descriptions is beyond the scope of this article)

<<Prev     Next>>