Antipatterns

Throughout dozens of projects, we have reviewed hundreds of use cases and have seen analysts doing weird things. In this chapter, we would like to present examples of what you should not do when creating use case specifications.

Use Case Name and Scenario

1. Don't include actor name in the scenario step - "Employee creates a customer" (more information here)
2. Don't include system either in the use case name or in the scenario - "Create customer in CRM"
3. Don't write names in the first person - I am creating user
4. The verb in the use case name should represent what the user wants from the system, so the verb should include some action from the system's point of view
   • Issue invoice, Create user
   • "Read messages" is not a use case. It is a user activity performed after the messages were displayed by the system - "Display messages" is the correct use case name
5. Avoid general words such as process, evaluate, data. The worst idea is to write "evaluate data".

Use Case Level of Detail

To kick off any software project, the analyst's goal is to first analyze user requirements and come up with a set of "user-level use cases". These use cases will provide the necessary information about what the software is expected to help users to accomplish. Documenting only the user-goal use cases helps to keep the level of detail consistent and to keep the number of use cases reasonable. If the use cases are too high-level, they very often describe business processes. They capture what the business user needs to do, but not what the software needs to. The information is valuable, but the goal of use cases is not to describe business processes. On the other hand, if the use cases include too much technical detail, it is wrong also. The list of use cases is then long, which makes it unmanageable.

Examples of very high-level or very low-level use cases can be found here.

We have also seen teams marking use cases as <<function>>, <<functional>> or <<internal>>. By doing this, analysts basically make those use cases technical, which is exactly what they should not do.

Implementation Details

It is also very common to see analysts creating use cases that try to include all possible information about the system. The scenarios then include user interface descriptions, responses to user interface events, algorithms descriptions, or business rules descriptions.

Example:

1. User enters name, age, weight into the dialog (use ui.components.dialog)
   • 
2. User clicks on "Save" button
3. System validates the age and weight
   • If age < 18 then the system doesn't validate the weight
   • If age >= 18 and <= 25 then weight must be < 100
   • If age > 25 then weight must be < 100
4. If weight and age combination don't pass the validation, the system displays a message: "Age and weight don't meet the required criteria, please correct the values and try again."
5. If everything is ok, system calls web service https://oursystem/api/saveUserData (HTTPS is needed otherwise the response is error code 403)
   • Input data: {name: $name, age:$age, weight: $weight}

The common argument of analysts who write scenarios like the one above is, it includes everything the developer needs to develop the functionality. This is true, but...

1. It is not the purpose of use case analysis to describe all aspects of the system. Use cases provide just an overview of the system goals, and including too many details is against their purpose. Besides, they are intended to be discussed with the business stakeholders, and including implementation details distract them and makes it very hard for them to read.
2. In the example above, the number of steps is still relatively low, and the use case is more or less readable. However, for more complex use cases, including all details may result in a use case of mass destruction. Such a use case has even more than 20 steps and includes absolutely everything, which makes it chaotic and impossible to manage.
3. Including implementation details in the use cases means rewrite and rework. Every time some detail changes, it must be reflected in the use case too. What is worse, it must be changed in all use cases which contain the specific implementation detail, such as a web service call or a screen design.

Functional Decomposition

Functional decomposition is the process of taking a complex problem and breaking it down into smaller, simpler parts. It is a standard technique that is more or less used during any system analysis, as it is more convenient to work with smaller pieces of the system than with the system as a whole. The problem is that it is not the purpose of use case analysis to do functional decomposition:

The above diagram is a demonstration of multiple antipatterns presented in this chapter:

• Use cases are too simple to express a user goal
• Use cases represent system features
• Use cases are nested to each other
• The diagram does not serve the purpose of outlining the basic user goals the system must support

It is not that the functional decomposition is bad, or that the information presented in the diagram should not be captured. It just should not be part of the use case analysis and should be described using other techniques.

Use Case Diagram Without Scenarios

Use cases are not diagrams, they are text. Describing use case scenarios and not including diagrams is absolutely fine since the diagrams only help to visualize the use cases. It does not work the other way around, though. Use case without scenario is useless and does not provide any value.

Deterrent Examples

In the separate section, we present examples of what you want to avoid when writing use cases.