The following guidelines concerning use case paths have proven effective when performing use case modeling during the requirements engineering of operational requirements.
Only specify a minimal set of normal and exceptional basis paths through the use case. Follow the Structured Testing approach to finding basis paths, the number of which is equal to the McCabe's cyclometric complexity of the potential interactions of the actors and the blackbox business, application, or component. Similarly, do not try to model every conceivable exceptional path, but only those paths that are significant and that may reasonably be expected to occur.
Rationale: This guideline limits the amount of use case modeling work to a practical level. Branching and looping that is visible at the interface can produce an indefinitely large number of paths.
Do not use branching and looping to combine multiple paths into a single use case path specification.
Rationale: Combining multiple paths into a single specification makes the paths more complex, makes it difficult to write common preconditions and postconditions, and makes it more difficult to use the paths to generate associated test cases.
Name each use case path with a unique, unambiguous, meaningful phrase that captures the essence of the path. The name should be consistent with, and implied by, the associated requirement, preconditions, interactions, and postconditions.
Rationale: This guideline improves communication by improving understandability.
Bad Example:
Good Example: Handle temperature sensor failure.
Provide a uniquely identified, unambiguous textual requirement for each use case path that captures its functional abstraction, preconditions, and postconditions.
Rationale: This guideline provides an overview of the use case path, it easier to understand. This guideline also promotes the testability of the resulting implementation. A textual requirement is also the information expected by domain experts who are used to textual requirements specifications. This guideline also supports the creation of an executive requirements summary document containing only the names and primary requirements of use cases and their paths.
Bad Examples:
Good Example: The digital thermostat shall allow the user to increment the desired temperature of the room when the desired temperature is less than the maximum desired temperature.
For each use case path, document both its preconditions and postconditions. Use assertions to capture required information formats and validation rules when interfacing with human actors, but use the external API specification to capture API formats and validation rules. Use preconditions to avoid specifying screen navigation details. If the assertions depend on the state of some object, then use state modeling to capture this information.
Rationale: Without preconditions, there is no way to determine what is required to execute the path successfully. Without postconditions, there is no guarantee that the execution was correct, even if the visible interactions were correct. Postconditions can be used to specify otherwise hidden internal constraints. Notice that preconditions and postconditions are thus path-specific and should therefore not be documented at the use case level. This greatly helps with the specification of the associated test cases.
Good Examples:
Completely document each interaction between the application and actors including the client and server of the interaction, the interaction itself, and any information that flows with the interaction. Use narrative English sentences that incorporate the vocabulary of the user or application domain, while avoiding the use of software engineering technical jargon. Document interactions initiated by actors in terms of the intention of the actor. Document interactions initiated by the application in terms of its requirements. Optionally document interactions between the actors, but only if it helps one understand the purpose of the interactions. Ensure that each interaction is actually an interaction and not really a precondition, postcondition, or traditional textual functional requirement or hidden calculation.
Rationale: It is important to know which is the client and which is the server in order to determine who provides the resulting service. In addition, only the interactions initiated by the application represent requirements. The specification is incomplete if it does not specify what information is passed with the interaction, and this information helps to identify classes in the corresponding object model. The interactions are confusing and hard to understand if preconditions, postconditions, and traditional textual functional requirements are incorrectly labeled as interactions.
Bad Examples:
Good Examples:
Specify the exceptional basis paths as well as the normal paths through a use case. Also document exceptional interactions as well as normal interactions, but avoid analysis paralysis due to trying to cover too many, extremely unlikely exceptional paths.
Rationale: Too often, requirements only specify how an application must function under normal circumstances, but not how it should function during abnormal circumstances. Requirements are therefore incomplete if only normal paths are specified. Exception handling software can often make up to 80% of business-critical or safety-critical software needing high operational availability and reliability. Unless exceptional paths are specified, there is little likelihood that they will be implemented or implemented correctly, and exceptional interactions must be documented if exceptional paths are to be completely documented. Testing exceptional paths and interaction is most likely to find defects. This guideline is critical if the resulting application is to be robust or have high operational availability.
Example path: Handle temperature sensor failure.
Example interaction: The digital thermostat software shall notify the user when the temperature sensor fails.
Categorize each use case path with its stability (how likely is it to change), frequency (how often does it execute), criticality (how important it is to the user), probability of defects (how likely are the developers to implement it correctly), and the resulting risk. Use values of high, medium, and low. Calculate risk as a function of stability, frequency, criticality, and probability of defects.
Rationale: The implementation of unstable paths may be postponed until the paths solidify, or else implementation may be moved forward in the schedule so that early prototyping may stabilize them. Reliability may be improved if limited test resources are allocated to paths that are executed frequently. Testers can emphasize the paths, the correct execution of which is critical to the user. Testing resources should also be allocated to those paths most likely to contain defects due to complexity or uncertainty (e.g., exceptional paths). This guideline allows one to identify the risk associated with each path in order to prioritize the scheduling of the development and testing of each path.
Use subordinate use case paths and the "invokes" relationship to factor out common cohesive sets of interactions. However, watch out for excessive functional decomposition of the use cases. Do this relatively late during use case modeling when the common interactions are known.
Rationale: This guideline simplifies the interactions and improves maintainability by eliminating unnecessary redundancy.
Example interaction: Perform use case path foo.
Where appropriate, document the logic of the use case (e.g., branching or optional interactions, looping, flexible orderings, and critical regions ) using pseudocode in the interactions and using logic boxes on sequence diagrams. However, branching can be ignored if interactions and sequence diagrams are documented one per path.
Rationale: This clarifies the actual behavior of the interactions. Often blocks of interactions can be performed in any order. Noting that the order of sets of blocks of interactions is undefined eliminates unnecessary workflow constraints on the human interface.
Example pseudocode:
Use blackbox sequence diagrams on whiteboards to informally analyze path interactions. Include blackbox sequence diagrams to formally document complex paths containing complex logic.
Rationale: Complex interactions are easier for most readers to understand if they are documented graphically.
Exception: Sequence diagrams contain information that is redundant with the textual interactions, which provide more information than the diagrams. Except for complex paths that require diagrams to improve understandability, one may wish to only temporarily create sequence diagrams on whiteboards during initial analysis and not maintain them in the documentation.
Formally specify those interactions that are initiated by the business or application as requirements using the standard terminology of requirements (e.g., the use of the term "shall"). Avoid unnecessary design constraints. For example, do not explicitly mention screen names or the closing of screens. Instead of specifying screen navigation, leave these as design decisions documented in the human interface design document. Uniquely identify each such requirement including each item in the list of information passed with the interaction.
Rationale: Any interaction initiated by the application is visible behavior and therefore required. Uniquely identifying requirements supports traceability.
Exception: Uniquely identifying requirements clutters up the requirements, making them less readable. A requirements management tool may automatically provide unique identifiers that can be turned off in the paper requriements specifications.
Bad Examples:
Good Example: The digital thermostat shall notify the new desired temperature to the user.
Document each postcondition as a requirement using the standard format for requirements (e.g., the use of the term "shall"). Uniquely identify each postcondition.
Rationale: A postcondition of the application is a required outcome of a use case path. Uniquely identifying requirements supports traceability.
Exception: Uniquely identifying requirements clutters up the requirements, making them less readable. A requirements management tool may automatically provide unique identifiers that can be turned off in the paper requriements specifications.
Bad Examples of postconditions of the "Decrement desired temperature" normal path of the "Change the desired temperature" use case include:
Good Examples of postconditions of the same path:
If a new value is the result of a complex calculation that occurs internally to the blackbox application, use a postcondition to explicitly specify the complex algorithm to be used to calculate the new value.
Rationale: Because the interactions only specify visible interactions between the application and its actors, they are not appropriate for specifying the complex algorithms sometimes needed to calculate a post-execution value.
Good Example: The new account balance equals the function foo() of its original value.
Use a standard format to document interactions. For example, interactions may be stereotyped as requests, responses, and event notifications. Use a technical writer to ensure compliance with the standard formats.
Rationale: This guideline greatly increases understandability and maintainability by avoiding insignificant differences that may confuse the reader.
Example Formats: