The System in So Many Words

This article will show you how to talk to a client so that you are both on the same page when designing a system and understanding what it will be required to do. It is excerpted from Prefactoring,  Written by Ken Pugh (O’Reilly; ISBN: 596008740). Copyright © 2007 O’Reilly Media, Inc. All rights reserved. Used with permission from the publisher. Available from booksellers or direct from O’Reilly Media.

WE MEET SAM, THE CLIENT, FOR WHOM WE ARE DEVELOPING A SYSTEM. Tim, a co-developer, and I interact with Sam to get an overall view of what he wants the system to do through use cases and prototypes. We work together to determine a common vocabulary to describe the system’s requirements.

Meet Sam

Systems are not developed in a vacuum. They are created to meet an organization’s needs. The client for whom a system is developed is the source of the requirements for the system and is the final decider of whether a system meets those requirements. Sam, the client, represents a composite of clients for whom I have developed systems over the years.

Sam owns the business CD Rental and Lawn Mower Repair. He started out with lawn mower repair and discovered that people who use lawn mowers like to listen to CDs and they prefer listening to a different CD each time they mow. Therefore, Sam came up with the idea of renting CDs. The service started out as a whim, but it has grown dramatically.

Sam contacted me about creating a system for keeping track of rentals in his store. His current system of using cards similar to library cards works, but it is unable to provide him the reports he feels his growing business requires.

Currently Sam has only one store. Since business is booming, he is considering opening several more stores. He wants us to design the system not only so it works in his store today, but so he can change it easily to accommodate multiple stores tomorrow.

Tim the Developer

Tim introduced me to Sam. Tim studied computer science in college and worked summers at Sam’s CD Rental and Lawn Mower Repair. He has been working as a programmer for five years, the last couple of years with me. He is back in school getting a master’s degree. We still work together, but mostly remotely. He takes courses and does some teaching, so he is often unavailable during the day, when I am talking with Sam.

Tim represents an amalgamation of programmers with whom I have worked. We work together on approaches to solutions, but usually work separately on code due to the remoteness factor. Because of our physical separation, code readability is extremely important.

Sam’s Request

Sam came up with some features that he wants to incorporate into his system. They are based on what he already does with his index cards, as well as additional ideas that he developed in his head. He listed them on a sheet of paper:

  1. I want to be able to keep track of where each CD is, both when it is in the store and when someone has rented it (including who has rented it).
  2. I want the system to report when CDs are overdue.
  3. I want a catalog so that customers can see what CDs are available and what songs are on them.
  4. When I have multiple stores, the system should show which stores have a particular CD.
  5. I want to be able to offer discounts to frequent renters.
  6. I want a charge system that enables me to bill customers per month rather than per rental.

{mospagebreak title=Sam’s Use Cases}

Sam, Tim, and I will develop the system with this list as the informal requirements for the system. We will transform these requirements into use cases.* I have found that writing use cases helps both me and the customer understand what the system needs to do. The cases are specified in sufficient detail so that we can appreciate the problem’s scope and magnitude. Additional detail can be added later so that when it comes time to design or code, the necessary detail is available. Working through a system’s use cases also helps to identify the users who should be consulted when their parts of the system undergo detailed specification and design.

Sam and I explore, in more detail, the first item on his list:

"Sam, who do you want to keep track of CDs?" I asked.

Sam replied, "What do you mean?"

I continued, "Do you want the customers to be able to check out their own CDs?"

"No," he answered, "only the clerk should perform checkout."

"Then let’s go through the steps of checking out a CD, since that sounds like a primary use case," I suggested.

"How about returning a CD?" Sam queried.

"That sounds like another one, so why don’t you tell me about both of them," I requested.

Sam explained the checkout and return procedures. After some discussion, I put his narration into the following informal use case descriptions. These use cases describe how the new system should work and are based on how the current manual process operates:


a. The customer brings a CD case to the clerk.

b. The clerk retrieves the actual CD corresponding to the case.

c. The customer presents his CD Store Customer Card. (The customer already has one of these for the manual system.) The clerk types the customer ID into the system.

d. The clerk types the CD ID into the system.

e. The system records that the CD is rented to that particular customer. It prints a rental contract.

f.  The customer signs the rental contract.

g. The clerk files the rental contract in a file box named "Signed Rental Contracts."


a. The clerk types the CD ID into the system.

b. The system records that the CD has been returned.

c. The system determines whether late fees apply and informs the clerk if that is the case.

An informal use case description can lead to enlightenment, especially when combined with an examination of what can go wrong at each step. I asked Sam what the clerk did in their current system if a customer did not have his CD Store Customer Card. He said that the clerk looks for the corresponding card in the customer file. We captured this information in another informal case.

Checkout_a_CD (extension if no customer ID)

a . The customer identifies himself using a photo ID.

b. The clerk enters information from the ID into the system.

c. The system searches for the customer ID using the information from the photo ID. If no matching customer is found, the system indicates an error.

The use cases presented so far are informal. They mix user actions with system actions. Some authors (e.g., Larry L. Constantine and Lucy A.D. Lockwood in Software for Use: A Practical Guide to the Models and Methods of Usage Centered Design [Addison-Wesley Professional, 1999]) suggest that the use cases be written in a more technology-independent manner. Actions that are unrelated to system processing will drop out of the flow and appear as comments. For example, the Checkout_a_CD use case might look like this:


a . The user enters the customer ID and the CD ID into the system.

b. The system records the entry. It responds by creating a rental contract for the customer to sign.

Notice that the actual way in which the IDs are entered into the system is not specified. The IDs could be scanned in using a bar code reader, typed in, or spoken and translated by a speech recognition program.

Initial use case descriptions might state exactly how customers expect the system to work. Before implementing the use cases, you can rework them into a more abstract, less-technology-dependent description. Removing the implementation details can help focus on the business policies and procedures that need to be programmed.

{mospagebreak title=The Ilities}

The purpose of requirements is not only to validate what the user wants, but also to verify that the implemented systems meet those wants. Requirements include more than just functional specifications as supplied by use cases. These other requirements relate to the software’s quality. They are often called the ilities, since many of the terms end in ility. These quality specifications include reliability, testability, deployability, and performance.

Often these quality requirements are not documented for a system. They are implicit, such as in the case of Sam’s system. It is assumed that the system will meet reasonable requirements. For example, its performance should ensure that users do not notice a delay.

For larger, more complex systems, documenting these quality requirements is essential. You can find further information on eliciting and documenting requirements in Software Requirements, Second Edition, by Karl E. Wiegers (Microsoft Press, 2003).

Reinvention Avoidance

Once Tim and I understand Sam’s system requirements, our first step is to determine whether an existing program provides the features that we need. There is no sense in recreating the wheel if an existing wheel works the way we want. Our goal as developers is to solve the clients problem, not to just write code.

Sam had searched for a commercial program and did not find anything. It appears that he is in a unique business, so nothing has been written, which is not surprising.*

We suggested to him that the process of renting a CD is similar to the process of renting a videotape or DVD. He could purchase one of those programs and it would already have many of the features that he wanted. He decided that he would rather have his own custom program instead of dealing with the terminology and handling differences among CDs and DVDs. We recommended that if he decides to expand into selling CDs, we should investigate retail sales systems. A lot of functionality already exists in those systems that should not be re-created. If a preexisting solution fits into the overall system, at least that part of the wheel need not be recreated.


Look for existing solutions to problems before creating new solutions.

Since Sam wants us to develop a custom system, Tim and I start to analyze the problem. We need to outline the concepts involved in the problem and clarify our understanding of what needs to be solved.

{mospagebreak title=What’s in a Name?} 

Names are important, not just for the code but also for requirements and analysis. If you don’t know what you’re talking about, it’s hard to design for it.

Sam described how he wants to keep track of the CDs. He also desired a catalog of all the CDs that he has for rent.

"So, what is a CD?" I asked Sam.

He paused for a moment and looked at me with a questioning expression on his face. He must have thought I was crazy. "You know, one of those round things you put in a CD player," he said.

"So, when you said you want a CD catalog, do you mean you want an entry in it for every round thing you have in your store?" I asked.

He paused again. "No, I want only one for each title, regardless of how many copies I have in the store."

I suggested, "So, let’s decide to use two terms, one for the CD title and one for the CD copy. This way we minimize the opportunity for misunderstanding. What do you want to call each thing?"

"Now I see what you mean," he replied. "What do you suggest?"

I replied, "Let’s call the title a CDRelease, and the other a CDDisc. We could use the name CDTitle, but that would start to get confusing when we talk about the title of a CDTitle. To clarify what we mean even further, we can describe each term with a sentence:

A CDRelease is a CD identified by its Universal Product Code (UPC).

A CDDisc is a physical copy of a CDRelease. CDDiscs, not CDReleases, are what are rented.

"Now is it possible that a CD which a customer would be looking for would be related to two different UPCs?" I asked.

"It’s possible," he said. But I don’t think we need to worry about that. One would usually have the term rerelease in its title."

"We can always revisit this question if things change," I said. "Let’s alter your requirements and the use cases to utilize these terms."

At this point, Sam and I came up with the following list of modified requirements:

  1. Keep track of where each CDDisc is, both when it is in the store and when someone has rented it (including who has rented it).
  2. Report when a CDDisc is overdue.
  3. Have a catalog so that customers can see which CDReleases are stocked, what songs are on each CDRelease, and which corresponding CDDiscs are available in the store.

Here is a modified use case:


a . The user enters the customer ID and the CDDisc ID into the system.

b. The system records the entry. It responds by printing a rental contract for the customer to sign.

Names are subjective. As long as you and the client agree on a name, it does not matter if the name makes sense to the outside world. Here are some other possibilities for names of these two concepts:

A CD identified by a UPC

A physical CD of a particular CDUPC

A CD identified by a UPC

A physical CD copy of a particular CDCatalogItem

Attributes of these classes should use the same names as the customer uses. If the customer uses a full name, avoid making up an abbreviation for it. If the customer uses an abbreviation or acronym, use that. If you have a hard time recalling what the short form means, ask the customer to supply a longer name.


Create a clearly defined name for each concept in a system.*

{mospagebreak title=Splitters Versus Lumpers}

If the world were perfect, you would have exactly one unique name for each concept in a system. In this imperfect world, having two concepts with the same name leads to confusion. In Sam’s case, the term CD was applied to both a CDRelease and a CDDisc. Separating the two concepts with two names clarified the requirements.

Using two different names for a single idea can also be confusing, albeit less so than two ideas with a single name. Referring to a physical CD as both a CDDisc and a CDPhysical might be justified by political measures. ("This department calls it this and that department calls it that.") Sam referred to the act of renting a CD as both renting a CD and checking out a CD. If these two terms really encompass the same operation, the duality of reference can be annoying, but might not be confusing.

Sometimes it is hard to determine whether you have two independent concepts or one. Try making up a one-line definition for a name. If it is difficult to create a simple definition, go ahead and use two names. Later on, if you find that the distinction was meaningless, you


I worked with a group responsible for developing an airline reservation system. There is a lot of interesting terminology in the airline business. Think of your concept of a "flight" as a passenger. When you fly from Boston to Peoria, do you say that you are taking a flight to Peoria? Do you say that, even if you make a connection in Chicago? In that case, would you refer to it as a "connecting flight"? If you were on Flight 80 from Boston to Chicago and on Flight 100 from Chicago to Peoria, would you say that you are on two different flights? Suppose that Flight 80 landed in Albany on the way to Chicago. Are you on three different flights?

The reservations people agreed on the following definitions:


A trip with a single departure and arrival. For example:

Boston to Albany on Flight 80

Albany to Chicago on Flight 80 Flight


A numerically designated set of segments, with the departure location of the subsequent segment the same as the arrival location of the previous segment. For example:

Flight 80 Miami to Boston to Albany to Chicago to Seattle

Flight 100 Dallas to Chicago to Peoria


A set of one or more consecutive flight segments on a flight. For example:

Flight 80 Boston to Albany to Chicago


A set of one or more legs for a passenger that takes a passenger from a departure location to an arrival location. For example:

Flight 80 Boston to Albany to Chicago and Flight 100 Chicago to Peoria

These consensus definitions made it easy to create higher-level concepts, such as "marriage." A marriage is a journey, for which the cancellation of one leg results in the cancellation of all legs of the journey.

can always declare the two names to be synonyms. Suppose that Sam and I came up with the terms CDAlbum and CDRelease. We might distinguish them by stating that a CDAlbum is a collection of songs with a title given to the set, and a CDRelease is a collection of songs that was released on a single CDDisc.

The conversion from one style of architecture, design, or coding to another is not necessarily symmetrical. Suppose that a single name has been used to denote two ideas. Later you decide that you need to replace that name with appropriate names for each idea. You need to examine each usage of the term carefully to determine which of the two concepts it represents. On the other hand, suppose that you have used two different names for a single concept. If you want to combine those into a single name, you can do a simple global replacement.

For example, suppose we have a class called Message, which represents messages displayed to the user. We think at the beginning that these messages are going to behave differently, so we divide them into WarningMessages, ErrorMessages, SevereErrorMessages, and ReallySevereErrorMessages. We make every message an object of one of these four classes. Later on, we realize that SevereErrorMessages and ReallySevereErrorMessages really do not behave differently. We can eliminate the distinction using a simple search and replace. Conversely, if we had not distinguished the two and later found that there should be a difference, we would have to look closely at each object of SevereErrorMessage to determine whether it should be categorized as ReallySevereErrorMessage.


It is easier to combine two concepts than it is to separate them.


Please check back next week for the conclusion to this article.

Google+ Comments

Google+ Comments