Defining the Initial Use Cases

As soon as we agreed on the project's vision, we started work on the initial use cases. A use case describes important interactions between an actor (usually a person) and the software system. These interactions must yield a result of value to the actor. ^[3]

^[3] RUP contains a couple of definitions of use case in its glossary. One that we prefer is: "A description of system behavior, in terms of sequences of actions. A use case should yield an observable result of value to an actor. A use case contains all flows of events related to producing the 'observable result of value,' including alternate and exception flows."

Figure 5.6 shows a use-case diagram for the initial set of use cases we identified for PSP Tools. Each use case is represented by an oval. The associated actor is represented as a stick figure.

Figure 5.6. Initial use-case diagram

To create the use case descriptions, we again used a RUP template. We identified the use cases that we thought we'd need to implement, and assigned a title, determined the actor, and wrote a brief description. That's all we needed to do for the Inception phase. ^[4] As the project progressed, we added information including the basic flow of events (the part that describes how the actor and the system interact) and the alternate flows of events (what happens if there's an error or the actor makes a nondefault choice)

^[4] Depending on the size and needs of your project, you may decide to detail a small number of use cases or scenarios during the Inception phase. On our small project, we placed a higher priority on getting out of Inception quickly and we chose to delve into the details more thoroughly during the Elaboration phase.

We started with many more use cases than we ended up with. During the project we realized that we could collapse multiple use cases into one, and we scoped others out of the project. We reorganized use cases primarily during the Inception phase, while we continued to eliminate features throughout the project. When we exited the Inception phase, our set of use cases was much smaller, as shown in Figure 5.7. We added an actor, Any User , and shortened the names of the two actors we had. We clarified the names of the use cases and collapsed some. For example, we merged the use cases for "Count Items" and "Time Activity" into "Record Personal Engineering Statistics" as alternate flows of events. We also added details such as entering defect information to the use case, something we overlooked in our first attempt at creating a use case model (see the sidebar on Models).

Figure 5.7. Use cases at the end of the Inception phase

This illustration is an example of a high-level view of the system. You can work with it before you commit your engineers to writing code. As you can see, this system view does not provide much detail, but it does help you understand the relationship between actors and use cases.

The use cases helped us use a common language to more clearly establish the boundaries and different areas of the system. The use cases also helped all team members understand what work they needed to accomplish, including in the areas of design, implementation, testing, and documentation. It is easy for technical and nontechnical project members to understand use cases. They provide a communication glue for the team. By starting with just the names of the use cases and the actors for the use cases, we were able to quickly define what we thought PSP Tools would look like in its first release.

Models

A model is simply an abstraction of one or more aspects of a system. It is a "complete description of a system from a particular perspective ('complete' meaning you don't need any additional information to understand the system from that perspective)." ^[*] One model is never sufficient to describe all aspects of a system.

Models may take different forms. You can use diagrams, physical models (often used in engineering disciplines other than software), mathematical formulae, and so on. In software, UML diagrams may be used to construct one or more models of the system under construction. The source code and its organization form another type of model, called the implementation model . RUP describes several types of models and provides guidance on how to construct and represent them.

Models are constructed for a purpose. One purpose is to improve communication and clarity about a system. Another purpose is to actually generate the system, or parts of it, from a model. This practice is known as Model-Driven Development (MDD). There are many ongoing MDD research and development initiatives in industry and academia. One Web site that contains links to MDD material is http://www.iturls.com/English/SoftwareEngineering/SE_mod1.asp.

^[*] RUP 2003 Glossary.

The surprise is that by implementing just a few use cases, we were able to produce a useful, working piece of software. We did not need to write pages and pages of specifications to capture every last detail, though for more complex projects or for risky parts of the implementation, a specification is necessary. Instead, the use cases serve as a way of saying, "When the system is successfully implemented, the user will be able to perform Task X by following these high-level steps."

But notice that implementing each use case implies that the system meets certain prerequisites. For example, "Open Project Database" implies that someone has designed the database, and that there's a way to create and populate a database. None of these steps have real value to the user; hence, they are not separate use cases. They are just stepping-stones to the parts of the system that the user cares about ”automating PSP.

Two points are worth mentioning about our use cases. First, we ended up with very few use cases to describe our system. Often people think they need dozens, if not hundreds, of use cases to describe a system. They end up creating many small scenarios or descriptions of behavior that are not, in themselves , a complete sequence of steps that deliver value. Even very large systems can be described by a couple of dozen use cases, each of them richly described with many alternate flows of events.

The second point, and one that we will mention several times while telling the rest of our story, is that we did not become prisoners to format or formality when we created our use cases. Our goal was to build software and we were determined to use the process and its artifacts to help us communicate, not hinder, progress. For a small team, even one that was not located in a single place, this worked fine. Our experience tells us that on a larger team, we would need to adopt more formality for some of our artifacts.

We don't claim that our use cases were perfect. We worked on the principle of making them good enough for our purposes. One might question our approach, but in fact most successful projects are just good enough for what they need to be; we think it's wasteful to spend time improving things that do not matter. There are many good resources on use cases that can help you decide how much detail to put in them. We have listed some of our favorites in the bibliography. Enough said about this topic. Let's move on.

A Few Words About Diagrams

Figures 5.6 and 5.7 were clearly produced by a tool. You might wonder if it is necessary to use a tool for your diagrams. As with use cases, our advice is to do what is right for your purposes.

None of our team members are expert modelers. But we use a diagram in a model when it helps communicate information effectively. We sometimes created diagrams on paper or whiteboards . Some of these we kept, some we threw away. At the beginning of the project we threw most of them away. At some point, a diagram matures to the point where it approaches stability. At that point we might commit it to a more permanent, persistent, form by using a tool. Your individual preferences and project needs determine that point.

You also need to decide how to use your model. Many teams use models, as we did, just for communication. Others use models to generate code. We decided to develop our models to a high level of detail to communicate the key ideas and structures of the PSP Tools software. We decided not to use our models to generate code. Later, we reverse-engineered the code to create class diagrams as a way to document our project. This is a relatively low-cost effort and it had value to us.

We took the view expressed in a paper by David Parnas and Paul Clements in 1986, "A Rational Design Process: How and Why to Fake It." ^[5] When we were done with the project, we wanted to make it look like we had done everything "right," according to some accepted set of rules. In reality, you can never get everything right over the course of a project. So, at the end of the project, spend some time cleaning up so that whoever works on the project next (including yourself) can understand what you have done. Make it easy to maintain and improve your work.

^[5] IEEE Transactions on Software Engineering , Vol. 12, Issue 2, February 1986.

Gary often created sequence diagrams directly in a tool. He liked the ability to quickly delete objects from the diagram. The tool also made the diagram neater. (If we had to describe Gary's drawing ability, all we can say is that he's a good programmer.)

We began using Rational Rose as the modeling tool of choice. Part way through the project, Rational released XDE (eXtended Developer Experience), a modeling tool that is integrated with a Java development environment, in our case, with the Eclipse integrated development environment (IDE). We chose to switch to the more integrated environment. Because our model was not complex, converting from one tool to the other was easy.

Identifying Nonfunctional Requirements

While most of a system's requirements can be captured through use cases, there are some requirements that cannot be expressed with use cases. We call these "nonfunctional requirements." For example:

• Your product will be sold in another country, so you must design it for international consumption.

• Your product must meet certain performance and quality benchmarks.

• Your product must comply with certain laws or standards, or contain features that allow the product to vie with competing products.

You should create actual nonfunctional requirements for these items so that you can track them, manage them, and, eventually, verify that the system fulfills them.