Chapter 2. Gathering Requirements: Give Them What They Want
Everybody loves a satisfied customer. You already know that the first step in writing great software is making sure it does what the customer wants it to. But how do you figure out what a customer really wants? And how do you make sure that the customer even knows what they really want? That’s where good requirements come in, and in this chapter, you’re going to learn how to satisfy your customer by making sure what you deliver is actually what they asked for. By the time you’re done, all of your projects will be “satisfaction guaranteed,” and you’ll be well on your way to writing great software, every time.
You’ve got a new programming gig
You’ve just been hired as the lead programmer at a new start-up, Doug’s Dog Doors. Doug’s got a pretty high-tech door under development, and he’s decided you’re the programmer that can write all the software to make his killer hardware work.
Todd and Gina: your first customer
Todd and Gina want more than a “normal” doggie door. Todd has everything from his plasma TV to his surround sound stereo to his garage door operating off of a remote control, and he wants a dog door that responds to the press of a button. Not satisfied with a little plastic flap letting their dog in and out, they’ve given Doug’s Dog Doors a call... and now Doug wants you to build them the dog door of their dreams.
Let’s start with the dog door
The first thing we need is a class to represent the dog door. Let’s call this class DogDoor, and add just a few simple methods:
Let’s write another class, Remote, to allow a remote control to operate the dog door. Todd and Gina can use the remote to open the dog door without having to get out of bed.
Be careful... you may not need all the magnets.
public class Remote {
private ___________ door;
public Remote(_____________ _______) {
this.door = door;
}
public void pressButton() {
System.out.println("Pressing the remote control button...");
if (_____._______()) {
door._________();
} else {
door._________();
}
}
} |
|
But when Gina tried it...
But the door doesn’t work the way Todd and Gina want it to!
Todd and Gina didn’t expect to have to close the dog door, so they pressed the button on the remote only once: to let Fido out.
Even worse, in this case, the way they used the door created new problems. Rats and rabbits started coming into their house through the open door, and you’re taking the blame.
Let’s tackle Todd and Gina’s dog door again, but this time, we’ll do things a little bit differently. Here’s our plan:
Listen to the customer
When it comes to requirements, the best thing you can do is let the customer talk. And pay attention to what the system needs to do; you can figure out how the system will do those things later.
Gina: And we want the door to automatically close after a few seconds. I don’t want to have to wake back up in the middle of the night to close the door.
You: Do you want a single button on the remote, or both an “Open” and “Close” button?
Todd: Well, if the door always closes automatically, we really don’t need separate “Open” and “Close” buttons, do we? Let’s just stick with a single button on the remote control.
You: Sure. So the button opens the door if it’s closed, and it can also close the door if it’s open, just in case the door gets stuck.
Todd: Perfect. Gina, anything else you can think of?
Gina: No, I think that’s it. That’s the dog door of our dreams.
Creating a requirements list
Now that we know what Todd and Gina want, let’s write down our new set of requirements. We don’t need anything too fancy...
You need to understand how the dog door will be used.
You’ve figured out one of the hardest parts about getting a customer’s requirements—sometimes even the customer doesn’t know what they really want! So you’ve got to ask the customer questions to figure out what they want before you can determine exactly what the system should do. Then, you can begin to think beyond what your customers asked for and anticipate their needs, even before they realize they have a problem.
What does the dog door really need to do?
You know what Todd and Gina want the dog door to do, but it’s your job to make sure that the door actually works. In the process, you may even come across some things that Todd and Gina want, but didn’t think about on their own.
Let’s write down exactly what happens when Fido needs to go outside:
Plan for things going wrong
Below is a diagram of how Todd and Gina’s dog door should work; all the numbers match up with the steps in our list in What does the dog door really need to do?. But things aren’t always going to go according to plan, so we’ve written down some things that might go wrong along the way.
Alternate paths handle system problems
Now that you’ve figured out some of the things that can go wrong, you need to update your list of things that needs to happen to make the dog door work. Let’s write down what should happen if the door closes before Fido gets back inside.
Yes! You’ve been writing use cases all along
When you wrote down the steps in getting Fido outside to use the bathroom, you were actually writing a use case.
A use case is what people call the steps that a system takes to make something happen. In Todd and Gina’s case, the “something” that needs to happen is getting Fido outside to do his business, and then back inside.
(Re) introducing use cases
You’ve been writing a use case for almost 10 pages now, but let’s take a closer look at exactly what that list of steps—the use case for Todd and Gina’s dog door—is really all about:
One use case, three parts
There are three basic parts to a good use case, and you need all three if your use case is going to get the job done.
Below is Todd and Gina’s use case, and a magnet for each of the three parts of a good use case (one part, Start and Stop, actually has two magnets). Your job is to identify where each magnet goes and attach it to the right part of the use case.
Todd and Gina’s Dog Door, version 2.0 What the Door Does
Fido barks to be let out.
Todd or Gina hears Fido barking.
Todd or Gina presses the button on the remote control.
The dog door opens.
Fido goes outside.
Fido does his business.
6.1
The door shuts automatically.
6.2
Fido barks to be let back inside.
6.3
Todd or Gina hears Fido barking (again).
6.4
Todd or Gina presses the button on the remote control.
6.5
The dog door opens (again).
Fido goes back inside.
The door shuts automatically.
Checking your requirements against your use cases
So far, you’ve got an initial set of requirements and a good solid use case. But now you need to go back to your requirements and make sure that they’ll cover everything your system has to do. And that’s where the use case comes in:
Is anything missing?
Now you need to look over the use case and see if everything the system needs to do is covered by the requirements.
Do your requirements handle everything?
Below on the left is the list of things that the dog door does, pulled straight from our use case in Checking your requirements against your use cases. Your job was to identify the requirement that handles each step of the use case, and write that requirement’s number down in the blank next to that step of the use case. You should have written down N/A for a step that didn’t require our system to do anything.
Did you find any steps in the use case that you don’t think you have a requirement to handle? If you think you need any additional requirements, write what you think you need to add to the requirements list down in the blanks below:
No, our requirements cover everything the system needs to do. We’re ready to actually write code to handle these requirements now, right?______________________
So now can we write some code?
With use case and requirements in hand, you’re ready to write code that you know will make Todd and Gina satisfied customers. Let’s check out our requirements and see exactly what we’re going to have to write code for:
Automatically closing the door
The only requirement left to code is taking care of automatically closing the door after it’s been opened. Let’s go back to our Remote class and handle that now:
We need a new simulator!
Our old simulator isn’t that useful anymore... it assumes Todd and Gina are closing the door manually, and not letting the timer do its work. Let’s update our simulator to make it work with the updated Remote class:t
Test drive, version 2.0
It’s time to see if all our hard work is going to pay off. Let’s test out the new and improved dog door.
It works! Let’s go show Todd and Gina...
Good catch... we need to test alternate paths as well as the main path.
Wouldn’t it be great if things worked just like you expected them to every time? Of course, in the real world, that almost never happens. Before we can show the new door off to Todd and Gina, let’s take a little extra time to make sure the door works when Fido doesn’t come right back inside after doing his business.
Your system must work in the real world...
...so plan and test for when things go wrong.
Reviewing the alternate path
Let’s make sure we understand exactly what happens on the alternate path, and then we can update DogDoorSimulator to test the new path out. Here’s the original main path diagram from Plan for things going wrong, along with the alternate path we figured out and added to our use case:
It’s time to update the simulator, but this time it’s your job to actually write some code. Below is what we have so far for DogDoorSimulator.
Your job is to match the code magnets at the bottom of the page to where they belong in the simulator. If you get stuck, check the diagram on the last page to see what’s going on at each step of the way. Oh, and there’s a twist... all the magnets for periods, semicolons, and parentheses fell off the fridge, so you’ll have to add those wherever they’re needed, too.
Test drive, version 2.1
Make the changes to your copy of DogDoorSimulator.java, and then recompile your test class. Now you’re ready to test out the alternate path of your use case:
Delivering the new dog door
Good use cases, requirements, main paths, alternate paths, and a working simulator; we’re definitely on the road to great software. Let’s take the new dog door to Todd and Gina.
Working app, happy customers
Not only did we turn Todd and Gina into satisfied customers, we made sure their door worked when Fido did something they didn’t expect—like stay outside playing.
Below on the left are some of the new terms you’ve learned in this chapter. On the right are descriptions of what those terms mean, and how they’re used. Your job is to match the term on the left with what that term’s purpose is on the right.
Time to write some more use cases.
Below are three more potential customers that are interested in Doug’s Dog Doors. For each customer, your job is to write a use case to solve the customer’s problem.
Answers in Sharpen your pencil answers.
Time to write some more use cases!
You’ve seen the customers; now let’s look at the use cases. Here is how we wrote our use cases for the dog-loving folks in Sharpen your pencil. See if your use cases look anything like ours.
Remember the three parts of a use case? It’s time to put what you’ve learned into action. On these pages, you’ll find several use cases; your job is to match the use case magnets on the bottom of the page to the correct parts of each use case.
Holly and Bruce’s Dog Door
Bruce scratches at the dog door to be let out. The dog door automatically opens, and Bruce goes outside. The dog door closes after a preset time. Bruce goes to the bathroom, and then scratches at the door again. The dog door opens automatically, and Bruce returns inside. The dog door then closes automatically.
If Bruce scratches at the door but stays inside (or stays outside), he can scratch at the door again to re-open it, from inside or outside.
Note
You should be able to follow these alternate use case formats without much trouble. If you get confused, check out Appendix A for the scoop on alternate use case formats.
John and Tex’s Dog Door
Secondary Actor: John
Preconditions: The dog door is open for Tex to go outside.
Goal: Tex uses the bathroom and comes back inside, without getting mud inside the house.
Main Path
Tex goes outside.
The dog door closes automatically.
Tex does his business.
John presses a button.
The dog door opens.
Tex comes back inside.
The door closes automatically.
Extensions
3.1 Tex gets muddy.
3.2 John cleans Tex up.
Answers in Use Case Magnets Solutions.
Remember the three parts of a use case? It’s time to put what you’ve learned into action. On these pages, you’ll find several use cases (in different formats, no less!); your job is to match the use case magnets on the bottom of the page up to the correct parts of each use case.
What’s the real power of use cases?
You’ve already seen how use cases help you build a complete requirements list. Below are several more use cases to check out. Your job is to figure out if the requirements list next to each use case covers everything, or if you need to add in additional requirements.
Answers in Sharpen your pencil answers
What’s the real power of use cases?
In each situation below, the use case describes how the dog door should work-but the requirements aren’t complete. Here are the things we saw that were missing from the requirement list, based on the ever-helpful use case.
Be careful! Good use cases make for good requirements, but a bad-or incomplete-use case can result in BAD requirements!
OOA&D is all about writing great software, and you can’t do that without making sure your apps do exactly what customers want them to.
In this chapter, you learned several tools for making sure your customers are smiling when you show them the systems you’ve built. Here are some key tools to keep handy:
* Readers of Head First Design Patterns will find these categories familiar... that’s because OOA&D and design patterns go hand in hand.
Down | |
4. The main path is sometimes called the ________ path. 5. A use case must have this (two words) to the user. 8. Requirements ensure that your system works _________. 10. In the dog door system, who was the external initiator? 13. Use cases focus on a ___________ user goal. 14. When Fido is here, the dog door has hit its stop condition. 16. A use case is just a list of things that a system _________. 18. A use case tells a ________ about how a system works. 21. Use cases are easiest to understand when they’re in this kind of language. 22. Good use cases make for ________ requirements. 24. A use case helps you understand how a system will be ______. 25. Use cases help you gather ___________. | 1. A use case details how a system __________ with users or others systems. 2. When things go right. you’re on this. 3. Use cases are all about the “______” of your system. 6. Without use cases, you won’t know if your requirements are ___________. 7. If you have four goals in a system, you’ll have at least this many use cases. 9. Good systems work in the _____ ________. 11. Fido does this to signal the start of the dog doors system’s use case. 12. When things go wrong, you end up on an __________ path. 15. Fido isn’t part of this, but his dog door is. 17. This is what you should do to the customer to gather an initial set of requirements. 19. How many use cases are there in Todd and Gina’s dog door? 20. Fido was chasing these when he got stuck outside. 23. A requirement documents this many needs. |
