C# ПІДРУЧНИКИ / Addison Wesley - Writing Effective Use Cases

Chapter 8. Extensions

Extension Handling - Page 110

condition. The goal is either to complete the use case goal, or to recover from whatever failure was just encountered. The body is a set of action steps, and possibly extensions to those action steps. The extension can end with delivery or abandonment of its goal, just as a use case. This similarity is not accidental, and it proves to be very handy in streamlining a complicated extension.

Start writing the handling of a condition with the action step that follows the condition being detected. You needn’t repeat that the condition was detected. Continue the story in exactly the same way as when writing the main success scenario. Use all the guidelines about goal level, verb style, and sentences discussed earlier. Keep writing until you reach a place where the main scenario can be rejoined or the use case fails.

Typically, the scenario fragment ends in one of just these ways:

•The step that branched to the extension has been fixed and replaced. At the end of the extension handling, the situation is as though the step had succeeded.

...

3. User activates web site URL.

4. ...

Extensions:

3a. No URL available:

3a1. User searches for web site.

3b. ...

•The system gives the actor another chance. At the end of the extension handling, the story is back at the beginning of the same step. Notice that the system will revalidate the password in the following example.

...

3.User enters password.

4.System validates password

5....

Extensions:

4a. Invalid password:

3a1. System notifies user, requests password again.

3a2. User reenters password.

4b. ...

•The use case ends, due to total failure.

...

3.User enters password.

4.System validates password

5....

Extensions:

...

4c. Invalid password entered too many times:

Chapter 8. Extensions

Extension Handling - Page 112

At some point, your indentation and numbering will become so complex that you will decide to break the extension out into another use case entirely. Most of the people who have written to me agree that this happens at about the third level of indentation.

Here is an example, taken from Use Case 22:“Register Loss” on page 83.

6a. Clerk decides to exit without completing minimum information:

6a1. System warns Clerk it cannot exit and finalize the form without date, name or policy number, or adjuster name provided.

6a1a. Clerk chooses to continue entering loss

6a1b. Clerk saves as "intermediate" report, and exits.

6a1c. Clerk insists on exiting without entering minimum information:

System discards any intermediate saved versions, and exits.

In this example, notice that the writer did not even put a number on the last line. Faced with numbering it 6a1c1, she decided that the extension was already cluttered enough, and that a short piece of straight text would be more readable.

In general, the cost of creating a new use case is large enough that people delay breaking an extension out into its own use case for as long as possible. The consensus seems to be that the above is as far as it makes sense to indent before doing so.

Creating a new use case from an extension

To break an extension out into a new, sub-use case, simply decide what the primary actor’s goal is, give the use case that name, name it at its new level (probably subfunction), open up the template for a new use case, and fill in the details that you pulled out of the calling use case.

Use Case 32:“Manage Reports” on page 146 illustrates just this case. Manage Reports once contained a step that said

User can Save or Print report at any time

It had a set of extensions describing the various alternatives and failure situations. But that list of extensions kept growing: unnamed report, preexisting name (do or don’t overwrite), user cancels save in the middle, and so on. Finally, the writers decided to put Save Report in its own use case.

In the original use case, you must still deal with the fact that the new sub-use case might fail, so your writing is likely to show both success and failure conditions.

From both a theoretical and effort point of view, it is a simple matter to move an extension into its own use case or back again. The use case model permits us to consider this a minor decision. It was no trouble to move the Save Reports extensions out, and similarly, it would only be a few minutes with the text editor to move them back into Manage Reports.

Chapter 8. Extensions

Page 113 - Extension Handling

However, the cost of creating a use case is not in the mechanical effort needed for the typing. The new use case must be labeled, tracked, scheduled, tested and maintained. These are expensive operations for the project team.

Keeping an extension inside the use case generally makes better sense economically. Two situations will drive you to create a new use case for the extension:

•The extension is used in several places. Putting the extension into its own use case means that it can be tracked and maintained in one place. Ideally, this is the only reason you ever create a use case below sea level.

•The extension makes the use case really hard to read. I find the limit of readability at around 2 pages of use case text, and three levels of indentation. (My use cases are shorter than most people’s, so your page length may be greater.)

Extension Handling Exercises

Exercise 32 Write the "Withdraw Cash" use case, containing failure handling, using "if" statements. Write it again, this time using scenario extensions. Compare the two.

Exercise 33 Find a requirements file written in a different form than with use cases. How does it capture the failure conditions? What do you prefer about each way of working, and can you capitalize on those observations?

Exercise 34 * PAF. Write the full use case using the PAF system, filling out the failure repair steps (PAF system described in Exercise 15 on page 68).

Chapter 9. Technology & Data Variations

Extension Handling - Page 114

9. TECHNOLOGY &

DATA VARIATIONS

Extensions serve to express that what the system does is different, but occasionally, you want to express that "there are several different ways this can be done". What is happening is the same, but how it is done might vary. Almost always, this is because there are some technology variations you need to capture, or some differences in the data captured. Write these into the Technology and Data Variations List section of the use case, not in the Extensions section.

Example 1.

Your system must credit a customer for returned goods. You write the action step,

7. Repay customer for returned goods.

They can be paid by check, by electronic funds transfer, or by credit against the next purchase. So you add:

Technology & Data Variations List:

7a. Repay by check, EFTS, or credit against future purchases.

Example 2.

You are specifying a new ATM. Technology has advanced to the point that customers can be identified by bank card, eye scan or fingerprints. You write:

Main Success Scenario:

...

2. User identifies him/herself, bank, and account #.

...

Technology & Data Variations List:

2a. Use magnetic bank card, eye scan, or fingerprints."

These points of variation are not extensions to this use case. Each would unfold into its own extension, at some lower level of use case, which you might never write. Each of these variations has a noticeable impact on your cost and work plan, so you need to capture and track them. You mark the possibilities using the Technology and Data Variations List.

The technology or deferred variations list is used quite rarely, and contains only a list, not action steps. If you find yourself putting conditions and action steps there, then you are using the section incorrectly.

Chapter 9. Technology & Data Variations

Page 115 - Extension Handling

The Technology and Data Variations section is used in Use Case 13:“Serialize access to a resource” on page 55.

Note: For those determined to use UML use case diagrams

Create an empty generic base use case for the basic step, and create a specializing use case for each variation. The empty generic base use case names the what but not any how. Each specialized use case gets to define its own steps explaining how it is done. The UML notation is explained in Appendix A.

Figure 17. Technology variations using specialization. .

Repay customer for returned goods

Repay by check

Repay by EFTS

Repay by purchase credit

Chapter 10. Linking Use Cases

Sub use cases - Page 116

10. LINKING USE CASES

10.1 Sub use cases

An action step can be a simple step or the name of another use case. The step,

User saves the report

with no emphasis or annotation indicates the step is a simple, atomic step. Writing either of

User saves the report

User saves the report (UC 35 Save a Report)

indicates there is a use case called Save a Report. This is so natural that it scarcely needs more

explanation. Even casual use case readers understand the idea, once they are told that underlined or italicized action indicates that there is another use case being called1, which expands the action

mentioned. It is extremely pleasant to be able to write use cases this way, rolling up or unrolling the

action as needed.

That is the easiest way of connecting use cases. It takes little time to learn and little space to

describe.

10.2 Extension use cases

On occasion, you need a different linkage between use cases, one closely modeled after the

extension mechanism. Consider this example.

You are designing a new word processing program, call it Wapp. The user’s main activity is typing. However, the user might suddenly decide to change the zoom factor or the font size, run the spell checker, or do any of a dozen different of things, not directly connected to typing. In fact, you want the typing activity to remain ignorant of what else might happen to the document.

Even more importantly, you want different software development teams to come up with new ideas for services, and not force them all to update the base use case for each new service. You want to be able to extend the requirements document without trauma.

The characteristics of such a situation are

*There is a main activity, which can be interrupted.

*It can be interrupted in a number of ways, without the main activity being in control 1.------In UML vocabulary, "another use case is included." I find that beginning writers and

casual readers are much happier saying that one use case refers to or calls another. Which term you use is up to you.

Chapter 10. Linking Use Cases

Page 117 - Extension use cases

of the interruptions.

This is different from having a main menu that lists the systems services for the user to select. The main menu is in control of the user’s choices. In the word processor example above, the main activity is not in control. It is simply interrupted by another activity.

In these sorts of instances, you do not want the base use case to explicitly name all the interrupting use cases. Doing so produces a maintenance headache, since every person or team adding a new interrupting use case has to edit the base use case. Every time it gets edited, it might get corrupted, it needs to be versioned, reviewed, etc.

In this situation, use the same mechanism as described for scenario extensions, but create a new use case. The new use case is called an extension use case, and is really identical a scenario extension, except that it occupies its own use case. Just as a scenario extension, it starts with a condition, referencing a situation in the base use case where the condition might occur. Put all that into the Trigger section of the template.

Here are some extracts for the word processor Wapp, to illustrate. Figure 18. shows the Wapp situation in UML diagram form. I carefully use a special style of connector, a hook, to show a use case extending (hooking into) another. See Appendix A for details.

Figure 18. UML diagram of extension use

1.User opens a document to edit.

2.User enters and modifies text.

...

... User saves document and exits application.

Use Case: Check spelling

Primary actor: user Scope: Wapp Level: subfunction!

Precondition A document is open

Trigger: Anytime in edit a Document that the document is open and the user selects to run the spell checker

Chapter 10. Linking Use Cases

Extension use cases - Page 118

Main success scenario:

...etc....

Use Case: Find synonym

Primary actor: user Scope: Wapp

Level: subfunction!

Precondition A document is open

Trigger: Anytime in edit a Document that the cursor is in a word and the user selects to run the thesaurus.

Main success scenario:

...etc....

Use Case: Change document template

Primary actor: user Scope: Wapp Level: subfunction!

Precondition A document is open

Trigger: Anytime in edit a Document that the document is open and the user selects this function.

Main success scenario:

...etc....

When to use extension use cases

Create extension use cases only when you need to. They are harder for people understand and maintain. Two situations call for extension use cases.

The most common use is when there are many asynchronous or interrupting services the user might use, which should not disturb the base use case. Often, they will be developed by different teams. These situations show up with shrink-wrapped software such as word processors, as illustrated above.

The second situation is when you are writing additions to a locked requirements document. Susan Lilly writes,

"You’re working on a project with an iterative process and multiple drops. You have baselined requirements for a drop. In a subsequent drop, you extend a baselined use case with new or additional functionality. You do not touch the baselined use case."

If the base use case is not locked, then the extension is fragile: changing the base use case can mess up the condition mentioned in the extending use case. Be wary about using extension use cases is such situations. Exercise 36, below, gives you a chance to experiment with this sort of extension use case.