discovering.tex

\chapter{Doing design (1 of 2)}
\label{design1}

\index{analysis}
\index{synthesis}
This chapter marks a watershed of sorts. Up to this point, we've been doing
\textbf{analysis} instead of \textbf{synthesis}. Analysis is when you look at
something that already exists -- a design diagram or a code snippet, say --
and seek to understand it, usually by breaking it down into its constituent
parts. Synthesis, on the other hand, is designing something that doesn't
already exist. Instead of scrutinizing a UML diagram, we're creating a UML
diagram; instead of examining a method, we're writing a method.

\index{ballplayer@\texttt{Ballplayer}}
Until now, I've presented you with example after example of classes and
methods already written, and diagrams illustrating their various parts. But
now it's time to ask the question: ``how do we figure out what the right
classes and methods \textit{are} in the first place?'' It's all well and good
for someone to hand us \texttt{Ballplayer}, \texttt{Team}, and
\texttt{Simulator} classes. But how did we know to create those particular
classes? Why not \texttt{Pitch}, \texttt{Catch}, and \texttt{Hit}? Why not
\texttt{FirstBaseman}, \texttt{Shortstop} and \texttt{Outfielder}, or
\texttt{NationalLeague} and \texttt{AmericanLeague}?

Going from the general idea of a program to a list of classes is tricky. It's
as much an art as a science. It calls for intuition and imagination more than
adherence to a set of rules. Nevertheless, there are principles that guide the
selection of good classes, and we'll talk about them in this chapter.

\index{Wirfs-Brock, Rebecca}
\index{responsibility-driven design}
Of all the OO pioneers who weighed in on the question of how to arrive at a
good design, the one who had the most influence on me was Rebecca Wirfs-Brock,
who invented the technique called \textbf{responsibility-driven design}. I'm
highly indebted to her, and recommend the original book authored by her and
her colleagues.\footnote{Wirfs-Brock, Wilkerson, Wiener, \textit{Designing
Object-Oriented Software.} Prentice Hall, 1991.}

\section{``Discovering the design''}

\index{discovering the design@``discovering the design''}
I don't know who first coined the phrase ``discovering the design'' (it
certainly wasn't me; it might have been Wirfs-Brock) but when I originally
heard it my ears perked up. It sounded strangely paradoxical. ``Design'' was
something one brought to the table and imposed on one's world, right? Not
something one found already there. ``Design'' seemed like a matter of
\textit{invention}, not \textit{discovery}; it was surely something you did to
a steam engine, not to a planet.

Yet hidden in this phrase is a powerful technique for OO design that attempts
to \textit{let the requirements speak for themselves.} One of Rebecca
Wirfs-Brock's great ideas was to begin with a written description of a
software program in action, and to cull from the language clues as to what the
``correct'' classes are.

Let me immediately clarify that ``correct'' does not mean ``there is one and
only one `right' set of classes'' for a particular program. In fact, there are
many such choices, some better than others, some downright awful. What we
mean by ``the correct classes'' is a set of classes (and their corresponding
inst vars and methods) that will:

\index{responsibilities}
\begin{compactitem}
\item represent the domain well
\item work seamlessly together
\item be amenable to adaptation as the system requirements evolve
\item distribute the responsibilities evenly among several classes
\item neither duplicate nor omit important functionality
\end{compactitem}

You get the picture. A good design is elegant, flexible, maintainable, and
robust to change. Many choices of classes will not meet these goals. A few
will. ``The correct set of classes'' means \textit{any} set of classes that
will do so reasonably well.

\section{Straight from the horse's mouth}
\label{reqSpec}

\index{requirements!specification (``req spec'')}
Wirfs-Brock's procedure is paraphrased in Figure~\ref{fig:discovering}. We
have to somehow come up with a written description to kick things off. Often,
a \textbf{requirements specification}\footnote{Sometimes called a ``req spec''
-- pronounced ``reck speck.''} has been authored by someone higher-up on our
company's food chain, and can be mined for much gold. Sometimes, we ourselves
take a step back and bang out a few paragraphs that describe what users do and
experience as they work with the system.

\setlength{\fboxsep}{10pt}
\begin{figure}
\centering
\definecolor{shadecolor}{rgb}{.9,.9,1}
\begin{shaded}
%\fbox{\parbox{.85\textwidth}{
\hspace{-.7in} Start with a written description of the software, and:
\smallskip
\begin{compactenum}
\itemsep.03in
\item Identify all noun phrases.
\item Eliminate obviously bad ones:
    \begin{compactenum}
    \item probable duplicates
    \item nouns that aren't instantiate-able
    \item things you obviously wouldn't represent
    \item likely \textit{attributes} of a class, not classes themselves
    \end{compactenum}
\item The remaining ones are your \textbf{candidate classes}. See which of
them ``feel right.'' Identify what each one \textbf{knows} and can \textbf{do}.

\end{compactenum}
%}}
\end{shaded}
\vspace{.1in}
\caption{Procedure for ``discovering the design.''}
\label{fig:discovering}
\end{figure}

The essential point is that the requirements themselves speak loudly about
what classes would be appropriate for the program it describes. Let's see how.

\subsection{Nouns, and only nouns}

\index{noun}
If you flash back to \textit{Schoolhouse Rock} or \textit{Sesame Street},
you'll remember your grammatical parts of speech and realize that a
\textbf{noun} is the right kind of word for a class name. Every object (and
therefore the class it's an instance of) is a ``person, place, or thing,'' not
an action word, modifier, or anything else.

Further, not just not any old noun will do. Consider the list in
Figure~\ref{fig:nouns}: these are all nouns, but only \textit{one} makes a
valid class name. Can you find it?

\setlength{\fboxsep}{1pt}
\begin{figure}[hb]
\centering
\fbox{\parbox{.95\textwidth}{
\begin{multicols}{3}
\begin{compactitem}
\small
\renewcommand\labelitemi{\freakingtilde}
\item happiness
\item Beyonc\'{e}
\item oxygen
\columnbreak
\item crocodile
\item teamwork
\item width
\columnbreak
\item communism
\item recreation
\item London
\end{compactitem}
\end{multicols}
}}
\vspace{.1in}
\caption{All nouns...but not all good class names.}
\label{fig:nouns}
\end{figure}
\normalsize

\index{noun!proper}
I claim the only legit class name in this list is
\underline{\textit{crocodile}}. Here's why. First, some of these entries are
``proper nouns'' which means they refer to specific instances of things, rather
than categories. In English, we almost always use \textit{capital letters} to
denote proper nouns, which means when you see ``Beyonc\'{e}'' and ``London''
you can immediately roll your eyes and move on.

\bigskip
\bigskip
\label{instantiation}
Second, most of the other nouns aren't \textit{instantiate-able}. Here's the
litmus test for whether a noun is instantiate-able: can you meaningfully
put the word ``a'' (or ``an'') before it? And can you meaningfully make it
plural and put a number (like thirteen) before it?

Clearly not. All of these phrases are plainly ridiculous:

\begin{multicols}{2}
\begin{compactitem}
\item four happinesses (?)
\item eleven oxygens\footnote{One could imagine a chemical analysis program
that dealt with oxygen atoms, among other things, and I've heard chemists
speak loosely of things like ``an extra oxygen'' or say ``that molecule has
five oxygens.'' I still like \texttt{OxygenAtom} much, much better as a class
name even here, though.} (?)
\item a teamwork (?)
\columnbreak
\item a communism (?)
\item nineteen recreations (?)
\end{compactitem}
\end{multicols}

Remember, the only thing we ever really do to a class is make instances of it,
to which we can do things. If you can't imagine a ``\texttt{new Communism()}''
or ``an \texttt{ArrayList} of \texttt{Happiness}es,'' it has no business being
a class.

\pagebreak
The closest contender to crocodile is the word \textit{width}. There may be
cases where this is a sensible class, but the reason I discard it is that a
width is almost certainly a \textit{modifier} of some other object, rather
than an object itself. One could imagine \texttt{Building}, \texttt{Image},
and \texttt{Rectangle} objects that all had an instance variable called
\texttt{width}; it's harder to imagine ``a width'' as an entity in its own
right, with its own properties and operations.

\subsubsection{Noun phrases}

\index{noun!noun phrase}
By the way, it's often the case that instead of a bare noun, we use a
\textbf{noun phrase} as a class name. A noun phrase is simply a noun with one
or more modifiers. ``Grizzly bear,'' ``chess tournament,'' and ``public liberal
arts college'' are examples.

\subsubsection{Singular, not plural}

\index{noun!singular}
Finally, it should hardly be worth stating that all class names must be
\textbf{singular}, not plural. I don't work in ``a buildings,'' but a
\textit{building}; and nobody has ``a dogs'' as a pet. When we instantiate an
object, we're going to say ``\texttt{Crocodile alice = new Crocodile()}'', not 
``\texttt{Crocodiles alice = new Crocodiles()}''.

\section{Carrying out the process}

\textbf{1. Identify all noun phrases.} Okay. We begin our semi-automated
process of deriving class names by starting with a written description of the
program's requirements. Here's a short example:

\index{bicycle}
\setlength{\fboxsep}{10pt}
\begin{center}
\label{blockRequirements1}
\large
\fbox{\parbox{.85\textwidth}{
\textsf{A bicycle store needs to manage its inventory. Shipments of various
models of bicycles are received every week from its suppliers, and customers
place individual orders for bikes and other accessories from the store. The
store manager must be able to place orders from vendors, maintain
contact information so they can be confirmed or canceled, and view lists of
the incoming products and their expected arrival dates. The manager also must
be able to record multi-item orders from individual customers, accept and
record down payments, and track inventory levels to ensure that enough items
are ordered to satisfy customer demand.}}}
\end{center}

Rebecca Wirfs-Brock's process from Figure~\ref{fig:discovering} calls for
sifting through the requirements description and \textit{circling all noun
phrases}. Unless it's an exact duplicate of one that previously occurred, be
conservative and circle every one. It would be a good exercise for you to do
this yourself in the box above, and then compare with my answer:

\setlength{\fboxsep}{10pt}
\begin{center}
\large
\fbox{\parbox{.85\textwidth}{
\textsf{A \bluebox{bicycle store} needs to manage its \bluebox{inventory.}
\bluebox{Shipments} of various
\bluebox{models} of \bluebox{bicycles} are received every \bluebox{week} from its
\bluebox{suppliers}, and \bluebox{customers}
place \bluebox{individual orders} for \bluebox{bikes} and other
\bluebox{accessories} from the \bluebox{store}. The
\bluebox{store manager} must be able to place \bluebox{orders} from
\bluebox{vendors}, maintain
\bluebox{contact information} so they can be confirmed or canceled, and view
\bluebox{lists} of
the \bluebox{incoming products} and their \bluebox{expected arrival dates}. The
\bluebox{manager} also must
be able to record \bluebox{multi-item orders} from \bluebox{individual
customers}, accept and
record \bluebox{down payments}, and track \bluebox{inventory levels} to ensure
that enough \bluebox{items}
are ordered to satisfy \bluebox{customer demand}.}}}
\end{center}

This is the raw material for the rest of the process. If we make everything
singular and lower-case, this leaves us with the following list:

\begin{samepage}
\begin{multicols}{3}
\small
\hspace*{.05in} \textsf{bicycle store}\\
\hspace*{.05in} \textsf{inventory}\\
\hspace*{.05in} \textsf{shipment}\\
\hspace*{.05in} \textsf{model}\\
\hspace*{.05in} \textsf{bicycle}\\
\hspace*{.05in} \textsf{week}\\
\hspace*{.05in} \textsf{supplier}\\
\hspace*{.05in} \textsf{customer}\\
\columnbreak
\hspace*{.05in} \textsf{individual order}\\
\textsf{bike}\\
\textsf{accessory}\\
\textsf{store}\\
\textsf{store manager}\\
\textsf{order}\\
\textsf{vendor}\\
\textsf{contact information}\\
\textsf{list}\\
\textsf{incoming product}\\
\columnbreak
\textsf{expected arrival date}\\
\textsf{manager}\\
\textsf{multi-item order}\\
\textsf{individual customer}\\
\textsf{down payment}\\
\textsf{inventory level}\\
\textsf{item}\\
\textsf{customer demand}
\end{multicols}
\end{samepage}

\textbf{2a. Eliminate probable duplicates.} According to
Figure~\ref{fig:discovering}, the next step is to eliminate likely duplicates.
Obviously things like ``bicycle'' and ``bike'' refer to the same conceptual
entity; we're hardly going to have a \texttt{Bicycle} class and a separate
\texttt{Bike} class in our program!

This isn't always 100\% straightforward, but it's usually 99\% so. Different
synonyms and turns of phrase are pretty easy to detect. I think we can be
pretty safe boiling this list down into a slightly smaller one, where
duplicates are shown:

\begin{samepage}
\begin{multicols}{2}
\small
\hspace*{.05in} \textsf{bicycle store (== store)}\\
\hspace*{.05in} \textsf{inventory}\\
\hspace*{.05in} \textsf{shipment}\\
\hspace*{.05in} \textsf{model}\\
\hspace*{.05in} \textsf{bicycle (== bike)}\\
\hspace*{.05in} \textsf{week}\\
\hspace*{.05in} \textsf{supplier (== vendor)}\\
\hspace*{.05in} \textsf{customer (== individual customer)}\\
\hspace*{.05in} \textsf{individual order (== order}\\
\columnbreak
\hspace*{.3in} \textsf{== multi-item order)}\\
\textsf{accessory}\\
\textsf{store manager (== manager)}\\
\textsf{contact information}\\
\textsf{list}\\
\textsf{incoming product}\\
\textsf{expected arrival date}\\
\textsf{down payment}\\
\textsf{inventory level}\\
\textsf{item}\\
\textsf{customer demand}
\end{multicols}
\end{samepage}

The choice of which synonym to retain is mostly aesthetic. All other things
being equal, I usually choose the shorter one.

\vspace{.3in}
\index{instantiation}
\textbf{2b. Eliminate nouns that aren't instantiate-able.} Now we apply our
test: ``can we put `a/an' or a number before the noun phrase, and have it make
sense?''

Actually almost all of these remaining entries pass that test, with the
exception of \textsf{customer demand}, and possibly \textsf{contact
information}. While one could indeed envision ``four or five customer demands''
in other contexts, it's pretty clear from the text that this is being used as
an abstract concept, not an individual object. ``Contact information'' is a
closer call, but by inspecting the requirements again, we can see that this is
really an attribute of \textsf{vendor/supplier}. We'll therefore strike the
idea of a ``\texttt{ContactInformation}'' class. We're now down to:

\begin{multicols}{3}
\small
\hspace*{.05in} \textsf{store}\\
\hspace*{.05in} \textsf{inventory}\\
\hspace*{.05in} \textsf{shipment}\\
\hspace*{.05in} \textsf{model}\\
\hspace*{.05in} \textsf{bicycle}\\
\columnbreak
\hspace*{.05in} \textsf{week}\\
\textsf{supplier}\\
\textsf{customer}\\
\textsf{order}\\
\textsf{accessory}\\
\textsf{manager}\\
\columnbreak
\textsf{list}\\
\textsf{incoming product}\\
\textsf{expected arrival date}\\
\textsf{down payment}\\
\textsf{inventory level}\\
\textsf{item}
\end{multicols}


\textbf{2c. Eliminate things you obviously wouldn't represent.} When you look
at some of these surviving noun phrases, you scratch your head. Would we
really have a ``\texttt{Week}'' class? Surely not. Also, although this program
will no doubt be used by the manager of a store, does it really make sense to
represent the \texttt{Manager} as an object? We'll cross out both of these.

\vspace{.2in}

\textbf{2d. Eliminate likely \textit{attributes} of a class.} Things are
getting a bit more subjective, but some of these remaining nouns definitely
seem ``too small'' to be their own classes. Consider \textsf{expected arrival
date}. Surely this is better modeled as a property of an order, rather than as
its own individual object. The same could be said for \textsf{down payment} and
\textsf{inventory level}. Generally speaking, noun phrases that seem to refer
to bits of data that have an obvious ``home'' in another class ought to be
modeled as inst vars, not classes.

\begin{samepage}
So now here's all that remains:
\bigskip
\begin{center}
\parbox{.8\textwidth}{
\begin{multicols}{2}
\begin{compactitem}
\item \textsf{store}
\item \textsf{inventory}
\item \textsf{shipment}
\item \textsf{model}
\item \textsf{bicycle}
\item \textsf{supplier}
\columnbreak
\item \textsf{customer}
\item \textsf{order}
\item \textsf{accessory}
\item \textsf{list}
\item \textsf{incoming product}
\item \textsf{item}
\end{compactitem}
\end{multicols}
}
\end{center}
\end{samepage}
\vspace{-.1in}

\label{candidate class}
We dub these our \textbf{candidate classes}, which essentially means ``those
noun phrases which each have a very good chance of actually turning into a
class in our program.'' We're not 100\% committed to them yet, but they pass
muster enough to deserve a deep think.

\vspace{.3in}

\textbf{3a. See which of the remaining ones ``feel right.''} We've come a long
way semi-mechanically. Now it's time to allow ourselves the luxury of turning
over in our minds each candidate class, ``trying it on,'' so to speak. 

It's here that a clear picture of our software system emerges. When I look at
the ten candidate classes, here's what comes to mind:

\begin{itemize}
\itemsep.1em

\index{requirements!specification (``req spec'')}
\item First, and most importantly, I realize that the word ``order'' was used
in \textit{two different ways} in the requirements description. You may have
actually noticed this earlier when we scratched out ``expected arrival date''
and ``down payment'' in step 2d. Those were both aspects of an order...but what
\textit{sort} of order? If we go back to the Bible (the req spec) we see these
two phrases:

\begin{quote}
\textsf{``...customers place individual orders for bikes and other accessories
from the store...''}
\end{quote}

\vspace{-.3in}
\begin{center}
and
\end{center}
\vspace{-.2in}

\begin{quote}
\textsf{``...The store manager must be able to place orders from vendors...''}
\end{quote}

Aha! Different beasts entirely. One is something Mrs.~Jamison places with
\textit{us};
the other is something \textit{we} place with Schwinn, Inc.

This sort of post-noun-phrase-stage epiphany isn't uncommon. English words are
used in a variety of ways, which makes them versatile and suggestive, yet
imprecise. Here, we clearly have two different notions of ``order'': (1) a
contract for delivery from one of our big suppliers like Trek or Cannondale
(which might include a dozen bikes or more), and (2) a customer's reservation
of a particular model/color/style of bike, which he or she is anxiously
waiting to take home for its first ride. More succinctly: one kind we buy, and
the other kind we sell.

We're going to have to invent at least one noun phrase of our own here, since
the req spec author double-dipped on the word ``order''; perhaps we'll call the
first one a \texttt{PurchaseOrder} and the second one a
\texttt{CustomerRequest}. (In situations like this, I think it's better to
\textit{avoid} using the original word altogether, since it was ambiguous to
begin with and therefore may encourage confusion down the road.)

\index{inheritance}
\item Second, I notice that some of these nouns have overlapping meanings, and
I sense that \textit{inheritance} might be applicable. In particular, consider
these four noun phrases:

\begin{quote}
\begin{center}
\textsf{bicycle \ \quad accessory \ \quad incoming product \ \quad item}
\end{center}
\end{quote}

These clearly all refer to things that can be purchased. When we go back to the
Bible, we see that the modifier ``\textsf{incoming}'' on \textsf{product}
really refers to the temporary state of a product (\textit{i.e.}, one in
transit from a supplier), not a fundamentally distinct kind of thing. So I'm
going to be bold, ditch ``incoming,'' and make these two assertions:

\pagebreak
\begin{compactenum}
\item \textsf{item == product}
\item \textsf{bicycle} and \textsf{accessory} are two different kinds
(subclasses) of \textsf{item}
\end{compactenum}

\end{itemize}

With these changes, our list is now:
\begin{center}
\parbox{\textwidth}{
\begin{multicols}{2}
\begin{compactitem}
\item \textsf{store}
\item \textsf{inventory}
\item \textsf{shipment}
\item \textsf{model}
\item \textsf{bicycle} (subclass of \textsf{item})
\item \textsf{supplier}
\columnbreak
\item \textsf{customer}
\item \textsf{purchase order}
\item \textsf{customer request}
\item \textsf{accessory} (subclass of \textsf{item})
\item \textsf{list}
\item \textsf{item}
\end{compactitem}
\end{multicols}
}
\end{center}

\vspace{.1in}


\textbf{3b. Identify what each one \textit{knows} and can \textit{do}.}

\index{encapsulation}
\index{state}
\index{behavior}
As you'll recall from Chapter~\ref{ch:encapsulation}, a well-conceived class
combines both \textbf{state} and related \textbf{behavior}. This is the
cornerstone of good object-oriented design.

\index{CRC card}
Hence at this stage, we apply this litmus test to the candidate classes that
remain. One tool to facilitate this procedure is creating a set of \textbf{CRC
cards}, which stands for ``Class, Responsibilities, Collaborations.'' The idea
is for your design team to create a literal $3\times5$ card for each candidate
class, put them on a flat workspace so you can move them around and compare
and group them, and see whether they seem to fit into a cohesive whole.

\index{class@\texttt{class}}
\index{responsibilities}
\index{collaborations}
The \textbf{Class} for each card is just the class name (which can be fluid as
you try to zero in on the best name). The \textbf{Responsibilities} include the
state (``what an object of that type knows'') and the behavior (``what an
object can do''), which I usually designate in separate sections. Finally, the
\textbf{Collaborations} are the other classes the class is likely to work
closely with to accomplish its job.

If you try to make a CRC card for a class, and have trouble coming up with
appropriate contents (particularly the Responsibilities section), that's a red
flag that perhaps this isn't a good class after all.

\begin{samepage}
Let's start at the top.

\bigskip
\label{bikeCRC1}
\index{shipment@\texttt{Shipment}}
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Shipment}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & which vendor is delivering it\\
& which purchase order it is fulfilling\\
& the expected arrival date\\
& the items in each shipment \\
\textit{Can}: & receive and add to inventory\\
& cancel \\
& update status \\
\hline
\textit{Collaborates}: & \texttt{PurchaseOrder}, \texttt{Item}, \texttt{Inventory}, \texttt{Supplier}\\
\end{tabular}\\
\hline
\end{tabular}
\end{center}
\end{samepage}
\bigskip

Our \texttt{Shipment} class looks like a good one. It clearly bears the
hallmarks of good OO design: it has state (information about what's in the
shipment, when it's due, and who it's from) and associated behavior (accept
it, cancel it, get an updated status).

You might be thinking, ``that's great, Stephen, but how did you know what to
write in that box?'' I admit it's not a turn-the-crank process. This is part of
the design process that's art, not science. Basically, though, you have to try
to create a little egocentric world in your mind, the center of which is the
class in question. 

Here, I said to myself, ``let's view the entire world through the lens of a
Shipment. First, in the real world, what ought a shipment to `\textit{know}'?''
The answer is things that relate directly to that shipment. The items it should
contain and the expected date of receipt are good examples. The number of
bicycles in the store is not, nor is a customer's contact information. Then, I
asked ``in the real world, what \textit{actions} pertain to a shipment?'' The
main one, of course, is to receive that shipment, which involves paying for it
and adding the items to the store. We also might ask the supplier for an update
if the shipment is past date, or even decide to cancel it and go with another
vendor if it's taking too long.

The important thing here isn't to get all the ``knows'' and ``cans'' 100\%
right -- things will evolve as our understanding evolves. It's more important
to recognize that there \textit{are} clear ``knows'' and ``cans'' for this
class, which certifies it as a bona fide entity within our object-oriented
system.

The ``Collaborates:'' list consists of those other classes we've identified as
likely co-participants in various system functions. A \texttt{Shipment} is
related to a \texttt{PurchaseOrder}, of course, since the former is the
fulfillment of the latter. Its also comprised of \texttt{Item}s, and will need
to update the \texttt{Inventory} levels when it arrives. It may need to call
methods directly on the \texttt{Supplier} class in the case where updates or
cancellations are necessary. Often the collaborations list just helps us
organize our thoughts (and our $3\times5$ cards) by grouping related classes
together.

Let's walk through a couple of other CRC cards.

\bigskip
\label{bikeCRC2}
\index{accessory@\texttt{Accessory}}
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Accessory}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & its name\\
& its manufacturer\\
& its part \#\\
& its cost \\
& its compatible bicycle models \\
\textit{Can}: & purchase \\
& find quantity in stock\\
& add to customer request  \\
\hline
\textit{Collaborates}: & \texttt{CustomerRequest}, \texttt{Model}, \texttt{Inventory}\\
\end{tabular}\\
\hline
\end{tabular}
\end{center}
\bigskip

An \texttt{Accessory} -- which we've tentatively identified as a subclass of
\texttt{Item} -- has attributes like name and cost, and also knows which bike
models (if any) it is compatible with. This prevents a customer from ordering
the wrong kind of bike seat or fender for a particular bicycle, for instance.
It can also be purchased (duh), either on the spot or as part of a special
customer order. It can also provide its quantity information by interfacing
with the \texttt{Inventory} class. Speaking of which...

\bigskip
\index{inventory@\texttt{Inventory}}
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Inventory}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & the quantity of each item in the store \\
\textit{Can}: & add items when shipments arrive \\
& remove items when purchases are made \\
& find quantity in stock \\
\hline
\textit{Collaborates}: & \texttt{Item} (and subclasses)\\
\end{tabular}\\
\hline
\end{tabular}
\end{center}
\bigskip

\index{Singleton pattern}
\index{design pattern!Singleton}
I smell a Singleton. Our store is likely going to have a single
\texttt{Inventory} object which can be used to query and update its item
quantities.

By the way, you may have noticed that one of the ``Can'' items --
``find quantity in stock'' -- was listed on the CRC card for both
\texttt{Accessory} and \texttt{Inventory}. This isn't wrong; probably an
\texttt{Accessory} object, when asked for its current quantity, will turn
around and query the \texttt{Inventory} singleton to produce that answer.
We've discovered a key shared function between classes.

That's the inventory of the store, and now for the \texttt{Store} itself:

\bigskip
\index{store@\texttt{Store}}
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Store}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & its inventory \\
\textit{Can}: & ? \\
\hline
\textit{Collaborates}: & \texttt{Inventory} \\
\end{tabular}\\
\hline
\end{tabular}
\end{center}

\bigskip
If we didn't realize it before, this is the moment when we discover that our
\texttt{Store} class is weak sauce. Turns out there really isn't anything for
a \texttt{Store} object to know or do, other than manage its inventory, which
of course is the job of the \texttt{Inventory} class. The CRC card process
revealed a false infiltrator, and we discard (literally) the \texttt{Store}.

\index{modularity}
You get the idea. I'll leave the other CRC cards as an exercise for the
reader. Remember, there are no hard-and-fast right answers to this process:
many different designs are possible, and it's only important to get a set of
classes that are cohesive, modular, encapsulated, and work well together.


\vspace{2.8in}

\pagebreak

\section{A longer example}

\index{requirements!specification (``req spec'')}
\index{Uno"!\textsuperscript{\textregistered}}
Figure~\ref{fig:uno} on p.~\pageref{fig:uno} gives a second, longer example of
a req spec. We'll develop this example in the remainder of this chapter and in
the next one. In particular, it involves a non-trivial inheritance hierarchy.

First, test yourself on identifying noun phrases, and see if you find the same
ones marked in Figure~\ref{fig:unoNouns}.

\begin{figure}[hb]
\label{blockRequirements2}
\centering
\small
\setlength{\fboxsep}{10pt}
\fbox{\parbox{.91\textwidth}{

\textsf{To test his intro student's algorithmic development skills, a professor
is developing an Uno!\textsuperscript{\textregistered} simulation program. The
simulator simulates a number of consecutive Uno games, each of which has four
players participating in it. Students write their own Player classes, which are
called by the simulator in order to play cards and call colors after wilds are
played.}

\vspace{.1in}

\textsf{Uno is a game played with a special deck of cards of various types.
Most cards have a color (red, blue, yellow, or green) and feature either a
number on them (from 0 to 9) or else a special action (like ``reverse,''
``skip,'' \textit{etc.}) Some cards are ``wild'' cards, which do not have any
particular color, and thus can be played at any time.}

\vspace{.1in}

\textsf{When play begins, the deck is shuffled, cards are dealt to each
player's hand, and one card is turned face up in the middle of the virtual
table, called the ``up card.'' Each player in turn gets a chance to play, by
playing a card from their hand on top of the up card. That up card is then
replaced by the new up card. If the deck is ever exhausted (\textit{i.e.},
runs out of cards) the discarded cards are reshuffled and placed beside the up
card to be drawn anew. The object of the game is to be the first player to
``go out'' by playing all cards from your hand.}

\vspace{.1in}

\textsf{In order to be legally played, a card must match according to certain
rules (either the color of the card played, or the rank of the card played,
must match the up card.) Some cards have special effects, involving reversing
the direction of play, skipping over player's turns, or causing unfortunate
players to have to draw additional cards from the deck.}

\vspace{.1in}

\textsf{When one player wins a round, he/she gets awarded points based on the
cards remaining in other players' hands. Each type of card has ``forfeit
cost,'' or point value that determines how much it is worth. As it runs, the
simulator maintains the cumulative scores of the players as they each win
games, so that at the end of 50,000 games, an overall winner can be declared.}
}}

\vspace{.1in}
\caption{The requirements specification for a game simulator.}
\label{fig:uno}
\end{figure}

\begin{figure}
\hspace*{-.4in}
\centering
\small
\setlength{\fboxsep}{10pt}
\fbox{\parbox{1\textwidth}{

\textsf{To test his \bluebox{intro student}'s algorithmic development
\bluebox{skills}, a \bluebox{professor} is developing an \bluebox{Uno
simulation program}. The \bluebox{simulator} simulates a number of consecutive
\bluebox{Uno games}, each of which has four \bluebox{players} participating in
it. \bluebox{Students} write their own \bluebox{Player classes}, which are
called by the simulator in order to play \bluebox{cards} and call
\bluebox{colors} after \bluebox{wilds} are played.}

\vspace{.1in}

\textsf{Uno is a \bluebox{game} played with a special \bluebox{deck} of cards
of various \bluebox{types}. Most cards have a color (red, blue, yellow, or
green) and feature either a \bluebox{number} on them (from 0 to 9) or else a
special \bluebox{action} (like ``reverse,'' ``skip,'' \textit{etc.}) Some cards
are \bluebox{``wild'' cards}, which do not have any particular color, and thus
can be played at any \bluebox{time}.}

\vspace{.1in}

\textsf{When play begins, the deck is shuffled, cards are dealt to each
player's \bluebox{hand}, and one card is turned face up in the middle of the
\bluebox{virtual table}, called the ``\bluebox{up card}.'' Each player in turn
gets a \bluebox{chance} to play, by playing a card from their hand on top of
the up card. That up card is then replaced by the new up card. If the deck is
ever exhausted (\textit{i.e.}, runs out of cards) the \bluebox{discarded
cards} are reshuffled and placed beside the up card to be drawn anew. The
\bluebox{object} of the game is to be the first player to ``go out'' by playing
all cards from your hand.}

\vspace{.1in}

\textsf{In order to be legally played, a card must match according to certain
\bluebox{rules} (either the color of the card played, or the \bluebox{rank} of
the card played, must match the up card.) Some cards have \bluebox{special
effects}, involving reversing the \bluebox{direction of play}, skipping over
player's \bluebox{turns}, or causing \bluebox{unfortunate players} to have to
draw additional cards from the deck.}

\vspace{.1in}

\textsf{When one player wins a \bluebox{round}, he/she gets awarded
\bluebox{points} based on the cards remaining in other players' hands. Each
type of card has ``\bluebox{forfeit cost},'' or \bluebox{point value} that
determines how much it is worth. As it runs, the simulator maintains the
\bluebox{cumulative scores} of the players as they each win games, so that at
the end of 50,000 games, an overall \bluebox{winner} can be declared.} }}

\vspace{.1in}
\caption{Noun phrases.}
\label{fig:unoNouns}
\end{figure}

Our mechanical noun phrase extraction produces this list:

\begin{samepage}
\begin{multicols}{3}
\small
\begin{compactitem}
\renewcommand\labelitemi{\raisebox{0.25ex}{\tiny$\bullet$}}
\item \textsf{intro student}
\item \textsf{skill}
\item \textsf{professor}
\item \textsf{Uno simulation program}
\item \textsf{simulator}
\item \textsf{Uno game}
\item \textsf{player}
\item \textsf{student}
\item \texttt{Player} \textsf{class}
\item \textsf{card}
\item \textsf{color}
\item \textsf{wild}
\columnbreak
\item \textsf{game}
\item \textsf{deck}
\item \textsf{type}
\item \textsf{number}
\item \textsf{``wild'' card}
\item \textsf{time}
\item \textsf{hand}
\item \textsf{virtual table}
\item \textsf{``up'' card}
\item \textsf{chance}
\item \textsf{discarded card}
\item \textsf{object}
\columnbreak
\item \textsf{rule}
\item \textsf{rank}
\item \textsf{special effect}
\item \textsf{direction of play}
\item \textsf{turn}
\item \textsf{unfortunate player}
\item \textsf{round}
\item \textsf{point}
\item \textsf{``forfeit cost''}
\item \textsf{point value}
\item \textsf{cumulative score}
\item \textsf{winner}
\end{compactitem}
\end{multicols}
\end{samepage}

Note that this req spec somewhat unusually refers to a specific
object-oriented \textit{class} (\texttt{Player}) which will of course become
one of our actual classes in the end.

\vspace{.1in}
\textbf{2a. Eliminate probable duplicates.} After eliminating likely
duplicates, our list is shrunk to:

\begin{samepage}
\begin{multicols}{3}
\small
\begin{compactitem}
\renewcommand\labelitemi{\raisebox{0.25ex}{\tiny$\bullet$}}
\item \textsf{student}
\item \textsf{skill}
\item \textsf{professor}
\item \textsf{simulator}
\item \textsf{game}
\item \textsf{player}
\item \textsf{card}
\item \textsf{color}
\item \textsf{``wild'' card}
\columnbreak
\item \textsf{deck}
\item \textsf{type}
\item \textsf{number}
\item \textsf{time}
\item \textsf{hand}
\item \textsf{virtual table}
\item \textsf{``up'' card}
\item \textsf{chance}
\item \textsf{object}
\columnbreak
\item \textsf{rule}
\item \textsf{rank}
\item \textsf{special effect}
\item \textsf{direction of play}
\item \textsf{turn}
\item \textsf{point}
\item \textsf{``forfeit cost''}
\item \textsf{cumulative score}
\end{compactitem}
\end{multicols}
\end{samepage}

An interesting decision here involved the terms \textsf{game} and
\textsf{round}. The former is used in a couple of different senses: Uno itself
is a ``game,'' yet the word ``game'' is also used to mean a single deal of the
cards, at the end of which one player goes out. Curiously, there's no noun in
the description for ``the overall match'' which comprises 50,000 games. We may
find we need such a class. In any event, I scratched \textsf{round} in favor
of \textsf{game} in the list above.

\vspace{.1in}
\textbf{2b. Eliminate nouns that aren't instantiate-able.} After getting rid
of the non-instantiate-able stuff, we shrink further to:

\begin{samepage}
\begin{multicols}{3}
\small
\begin{compactitem}
\renewcommand\labelitemi{\raisebox{0.25ex}{\tiny$\bullet$}}
\item \textsf{student}
\item \textsf{professor}
\item \textsf{simulator}
\item \textsf{game}
\item \textsf{player}
\item \textsf{card}
\item \textsf{color}
\columnbreak
\item \textsf{``wild'' card}
\item \textsf{deck}
\item \textsf{type}
\item \textsf{number}
\item \textsf{hand}
\item \textsf{virtual table}
\item \textsf{``up'' card}
\columnbreak
\item \textsf{rank}
\item \textsf{special effect}
\item \textsf{direction of play}
\item \textsf{turn}
\item \textsf{point}
\item \textsf{``forfeit cost''}
\item \textsf{cumulative score}
\end{compactitem}
\end{multicols}
\end{samepage}

It's worth drawing attention here to the noun ``\textsf{rule},'' which I
discarded. I find that many students' inclination is to keep \textsf{rule} as
a class, whereas I think the description makes it clear that ``rules in
general, according to which the game is played'' is what's intended. And that
would steer us away from instantiating some number of \texttt{Rule} objects.

\vspace{.1in}
\textbf{2c. Eliminate things you obviously wouldn't represent.} The only ones
I got rid of on this step were (ironically) \textsf{student} and
\textsf{professor}. Nothing personal.

\vspace{.1in}
\textbf{2d. Eliminate likely \textit{attributes} of a class.} I think you'll
agree that \textsf{color}, \textsf{type}, \textsf{number}, and \textsf{rank}
are best suited as attributes of a \texttt{Card} class, not as classes in
their own right. Too, \textsf{direction of play} -- which is simply
``clockwise'' or ``counter-clockwise'' -- seems like a property of the
\textsf{game}. Similar thinking leads to deleting \textsf{point} and
\textsf{cumulative score} (attributes of the \texttt{Player}s) and
\textsf{forfeit cost} (an attribute of a \texttt{Card}.) We're now left with
only:

\begin{samepage}
\begin{multicols}{3}
\small
\begin{compactitem}
\renewcommand\labelitemi{\raisebox{0.25ex}{\tiny$\bullet$}}
\item \textsf{simulator}
\item \textsf{game}
\item \textsf{player}
\item \textsf{card}
\columnbreak
\item \textsf{``wild'' card}
\item \textsf{deck}
\item \textsf{hand}
\item \textsf{virtual table}
\columnbreak
\item \textsf{``up'' card}
\item \textsf{special effect}
\item \textsf{turn}
\end{compactitem}
\end{multicols}
\end{samepage}


\textbf{3a. See which of the remaining ones ``feel right.''} This is honestly a
pretty darn good list. If I were to nitpick it further, I'd probably say that
\textsf{``up'' card} will probably turn out to be an instance variable of
\textit{type} \texttt{Card}, rather than its own class. I'd wager that
\textsf{turn} doesn't end up being a full-blown class either, since ``whose
turn it is'' is better served with an inst var.

The \textsf{``wild'' card} noun phrase is quite literally going to become a
wild card for us, as we'll discover in the next chapter. It conceals what is
really going to be a deep inheritance hierarchy, in which the different types
of cards are all subclasses of \texttt{Card}. This is where the
\textsf{special effect}s come into play as well -- in the end, I didn't model
this as its own class, but rather embedded the functionality into the
\texttt{Card} subclasses. Either way's okay, though.

\vspace{.3in}
\textbf{3b. Identify what each one \textit{knows} and can \textit{do}.}
I'll sign off this chapter by taking a crack at CRC cards for some of the
classes that are going to survive the whole design vetting. These are quality
classes that will ensure a solid design that's robust for the present and the
future!

\index{CRC card}
\label{unoCRC1}
\index{simulation@\texttt{Simulation}}
\small
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Simulation}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & the name of each player \\
& the \texttt{Player} subclass for each player \\
& how many total games to simulate \\
& how many games have been played so far \\
\textit{Can}: & play some number of games and compute final scores \\
\hline
\textit{Collaborates}: & \texttt{Game}, \texttt{Player} (and subclasses)\\
\end{tabular}\\
\hline
\end{tabular}
\end{center}

\index{card@\texttt{Card}}
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Card}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & its type \\
& its color (if applicable) \\
& its number (if applicable) \\
& its ``forfeit cost'' \\
& whether it can be legally played on an up card \\
& whether the player who played it can call a new color \\
\textit{Can}: & perform any special effect appropriate to its type \\
\hline
\textit{Collaborates}: & \texttt{Hand}, \texttt{Deck} \\
\end{tabular}\\
\hline
\end{tabular}
\end{center}

\index{deck@\texttt{Deck}}
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Deck}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & the contents of a standard Uno deck \\
& which face-down cards it contains, in order \\
& which face-up cards have been discarded \\
\textit{Can}: & draw a new card \\
& reshuffle (when empty) \\
\hline
\textit{Collaborates}: & \texttt{Card} (and subclasses)\\
\end{tabular}\\
\hline
\end{tabular}
\end{center}

\index{game@\texttt{Game}}
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Game}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & which player's turn it is \\
& the current direction of play \\
\textit{Can}: & start a simulation of a single Uno game \\
& advance to the next player \\
& reverse the direction \\
& observe the end of the game, and report scores \\
\hline
\textit{Collaborates}: & \texttt{Player} (and subclasses), \texttt{Hand},
\texttt{Deck} \\
\end{tabular}\\
\hline
\end{tabular}
\end{center}

\index{hand@\texttt{Hand}}
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Hand}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & which cards are being held \\
\textit{Can}: & defer to its controlling \texttt{Player} object to choose a card \\
& defer to its controlling \texttt{Player} object to call a color \\
& add a card (when the player must draw) \\
& count the ``forfeit costs'' of all its cards \\
\hline
\textit{Collaborates}: & \texttt{Player} (and subclasses), \texttt{Card}\\
\end{tabular}\\
\hline
\end{tabular}
\end{center}

\label{unoCRC2}
\index{player@\texttt{Player} (Uno"! example)}
\begin{center}
\begin{tabular}{|l|}
\hline
\texttt{Player}:\\
\hline
\begin{tabular}{rl}
\textit{Knows}: & its hand \\
& all cards that have been played since last shuffle \\
\textit{Can}: & select which card to play on the ``up card'' \\
& choose a color to call immediately after playing a wild \\
\hline
\textit{Collaborates}: & \texttt{Card}, \texttt{Game} \\
\end{tabular}\\
\hline
\end{tabular}
\end{center}

\normalsize