Designing the Deck Class

Imagine you are writing a card game and need a deck to play with. Before reading any method definitions, ask two simpler questions: what should a brand-new deck contain, and what should you have to tell the deck when you create it? Those two answers are the starting point for the specification of the Deck class, and they shape every method that follows. It is worth making your own guess first, because the specification is easier to follow once you know what problem it is solving.

The Deck is a stateful object. It begins in a known condition, and each method either changes that condition or reports on it. The most useful way to understand the class is to follow its state from the moment it is created. A new deck starts with 52 cards, all in a standard order, and that order is the same for every new deck. From that point on, the deck's contents change only through the operations the specification allows: dealing a card removes one from the deck, and shuffling puts used cards back and rearranges them.

Read the diagram as a set of states and transitions. The deck starts in the new state with 52 cards. Each dealCard() call moves it toward empty. Once the last card has been dealt, the deck is empty, and a further dealCard() call is an error. A shuffle() call returns used cards to the deck, so the deck can return to a full count from either the partly dealt state or the empty state. The diagram shows the card count and the reachable states, while the specification supplies the rules for each transition.

The constructor builds the deck, and it takes no parameters. The specification defines the starting condition completely: 52 cards in a standard order, identical for every new deck. Because that condition is fixed, the caller has no decision to make when creating a deck. Supplying arguments would imply a choice the specification does not offer. Keeping the two starting conditions separate in your mind also prevents a common confusion. A new deck is in a standard order, which is the same every time. A shuffled deck is in a random order, which is not the same from one shuffle to the next.

Once a deck exists, the specification gives it three operations: shuffle, dealCard, and cardsLeft. Each has a signature that tells a programmer what must be supplied and what comes back. Notice that only dealCard produces a value the caller must use. The other methods either change the deck's contents without returning anything, or return a count. This difference in return types is deliberate. It tells the caller what kind of information flows back from each operation.

The key point is where the behavior is specified. The fact that dealCard() throws an IllegalStateException on an empty deck is stated in the method's comment, which is part of the specification. A caller who reads the specification knows in advance that an empty deck is not a value to be handled quietly. It is an error the caller must avoid.

The surrounding program can avoid the error by checking the deck before dealing. The program asks cardsLeft() for the remaining count. If the count is greater than zero, it is safe to call dealCard(). If the count is zero, the program skips the deal. This check uses the deck's own answer, so it does not depend on a separate count kept by the program.