System Design Handbook · llms.txt
Object-oriented design questions
Lay a standard pack of playing cards on the table: 52 cards, four suits (hearts, diamonds, clubs and spades), and in each suit an ace, the numbers 2 to 10, and a jack, queen and king. Poker, blackjack, bridge and solitaire all use the same pack, but each game gives the cards different meanings. In blackjack a king is worth 10 and an ace is worth 1 or 11. The question asks you to model the pack once, in a way any game can reuse, and then build blackjack on top of it.
This is an object-oriented design question. Object-oriented design (OOD) means describing a program as a set of objects, each holding its own data and offering a few operations on it. In the interview you clarify the scope with a few questions, name the classes and what each one is responsible for, write the code, and then discuss how the design would change if the requirements grew. What the interviewer judges is how you split the problem: which parts are shared by every card game, which belong to one game, and how the two connect.
Ask these questions before writing any code. Each answer is what we assume for the rest of the chapter.
Two smaller assumptions fill gaps the questions leave open:
None instead of raising an error. The caller decides what an empty deck means in its game.The nouns in the problem are suit, card, deck and hand. Each becomes a class. Blackjack adds a blackjack card, which knows its blackjack points, and a blackjack hand, which knows how to score aces.
Suit is an enum, a type with a fixed set of named values: HEARTS, DIAMONDS, CLUBS and SPADES. Each value is the suit's symbol, so a card can print itself as Q♠.Card holds a rank and a suit. The rank is a number from 1 to 13: the ace is 1, the number cards are 2 to 10, and the jack, queen and king are 11, 12 and 13. Its value property gives the card's points in a game that doesn't say otherwise, which is just the rank. Card is a frozen dataclass: Python writes the constructor, equality and hashing for us, and nobody can change a card after it's made. A card is a value, like the number 7, so it shouldn't change.BlackjackCard is a subclass of Card. It overrides value: jacks, queens and kings are worth 10, and an ace is worth 1. Whether an ace should count as 11 depends on the rest of the hand, so the card leaves that decision to the hand. It adds is_ace() and is_face_card().Deck[C] holds a list of cards and a deal_index, the position of the next card to deal. Cards before the index have been dealt. It can report remaining_cards(), deal_card() and shuffle(). It is generic: the C in Deck[C] stands for whichever card type the deck holds, so a Deck[BlackjackCard] deals blackjack cards. Its standard() method builds the usual 52 cards of any card type, or several packs at once.fisher_yates() is the shuffling function the deck uses. It's a plain function, separate from the deck, so it can be tested on its own.Hand[C] holds the cards one player has. It can add_card(), and its score() adds up the cards' values.BlackjackHand is a subclass of Hand[BlackjackCard]. It overrides score() with the blackjack rule for aces, and adds possible_scores(), is_soft(), is_bust() and is_blackjack().Three object-oriented ideas carry the design:
BlackjackCard "is a" card and BlackjackHand "is a" hand. Code that works with any hand, such as printing it, still works with a blackjack hand.score() adds up values. The blackjack version replaces it, and nothing else changes.These are the blackjack rules the code needs. Number cards are worth their pip value, the number printed on them. Face cards (jack, queen and king) are worth 10. An ace is worth 1 or 11, whichever the player prefers. A hand whose total goes over 21 is bust and loses. A blackjack is a two-card hand of an ace and a 10-value card, and in the Bicycle rules it pays 3 to 2. A hand is soft when it holds an ace that is being counted as 11. A soft hand can't bust by taking one more card, because the ace can drop back to 1.
The scoring rule follows from these. Count every ace as 1 to get the hard total. Each ace you raise to 11 adds 10. The hand's score is the highest possible total that is 21 or less. If every total is over 21, the hand is bust, and its score is the lowest total.
Here is the complete program. It uses only the standard library and runs on Python 3.9 or later.
from __future__ import annotations
import random
from dataclasses import dataclass
from enum import Enum
from typing import Generic, Optional, TypeVar
class Suit(Enum):
HEARTS = "♥"
DIAMONDS = "♦"
CLUBS = "♣"
SPADES = "♠"
RANK_NAMES = {1: "A", 11: "J", 12: "Q", 13: "K"}
@dataclass(frozen=True)
class Card:
"""A playing card. rank runs 1 to 13: ace = 1, 2-10, jack = 11, queen = 12, king = 13."""
rank: int
suit: Suit
@property
def value(self) -> int:
"""Points in a game that doesn't override them: the rank itself."""
return self.rank
def __str__(self) -> str:
return f"{RANK_NAMES.get(self.rank, str(self.rank))}{self.suit.value}"
@dataclass(frozen=True)
class BlackjackCard(Card):
def is_ace(self) -> bool:
return self.rank == 1
def is_face_card(self) -> bool:
return 11 <= self.rank <= 13
@property
def value(self) -> int:
"""Face cards are 10. An ace is 1 here; the hand decides if it counts 11."""
return 10 if self.is_face_card() else self.rank
C = TypeVar("C", bound=Card)
def fisher_yates(items: list, rng: random.Random) -> None:
"""Shuffle items in place so every order is equally likely."""
for i in range(len(items) - 1, 0, -1):
j = rng.randint(0, i) # 0 <= j <= i, inclusive
items[i], items[j] = items[j], items[i]
class Deck(Generic[C]):
def __init__(self, cards: list[C], rng: Optional[random.Random] = None) -> None:
self.cards = cards
self.deal_index = 0 # cards before this index have been dealt
self.rng = rng or random.Random()
@classmethod
def standard(cls, card_type: type[C] = Card, num_decks: int = 1,
rng: Optional[random.Random] = None) -> Deck[C]:
cards = [card_type(rank, suit)
for _ in range(num_decks) for suit in Suit for rank in range(1, 14)]
return cls(cards, rng)
def remaining_cards(self) -> int:
return len(self.cards) - self.deal_index
def deal_card(self) -> Optional[C]:
if self.deal_index >= len(self.cards):
return None
card = self.cards[self.deal_index]
self.deal_index += 1
return card
def shuffle(self) -> None:
"""Gather every card back into the deck and shuffle all of them."""
self.deal_index = 0
fisher_yates(self.cards, self.rng)
class Hand(Generic[C]):
def __init__(self, cards: Optional[list[C]] = None) -> None:
self.cards: list[C] = list(cards or [])
def add_card(self, card: C) -> None:
self.cards.append(card)
def score(self) -> int:
return sum(card.value for card in self.cards)
def __str__(self) -> str:
return " ".join(str(card) for card in self.cards)
class BlackjackHand(Hand[BlackjackCard]):
BLACKJACK = 21
def possible_scores(self) -> list[int]:
"""Every total the hand can make, counting each ace as 1 or 11."""
hard = sum(card.value for card in self.cards) # all aces as 1
aces = sum(1 for card in self.cards if card.is_ace())
return [hard + 10 * k for k in range(aces + 1)] # k aces raised to 11
def score(self) -> int:
"""The best total: the highest one not over 21, or the lowest if all bust."""
scores = self.possible_scores()
under = [s for s in scores if s <= self.BLACKJACK]
return max(under) if under else min(scores)
def is_soft(self) -> bool:
"""True when an ace is counted as 11 in the best total."""
return self.score() != self.possible_scores()[0]
def is_bust(self) -> bool:
return self.score() > self.BLACKJACK
def is_blackjack(self) -> bool:
return len(self.cards) == 2 and self.score() == self.BLACKJACK
The key parts:
Deck.standard() creates one card for every suit and rank, repeated num_decks times. Passing BlackjackCard as card_type gives a deck of blackjack cards, and the deck code itself doesn't know anything about blackjack.deal_card() returns the card at deal_index and moves the index on by one. It never removes cards from the list, so shuffle() can bring them all back just by resetting the index to 0. remaining_cards() is the list's length minus the index.shuffle() resets the deck, then calls fisher_yates(), explained below. The deck takes an optional random.Random object, so a test can pass one with a fixed seed and get the same order every run.BlackjackHand.possible_scores() counts the aces and returns the hard total plus 0, 10, 20 and so on, one entry for each number of aces raised to 11. A hand of ace, ace, 9 has hard total 11 and possible scores [11, 21, 31].score() keeps the totals that are 21 or less and returns the largest. If none is left, it returns the smallest, which is the hard total.is_soft() is true when the best score differs from the hard total, meaning an ace is being counted as 11.Code for this question often has the right shape and still fails when you run it. These are the usual traps, and how this version avoids each one:
value on Card. If Card declares value as abstract, plain cards can never be created, and the generic deck can only hold blackjack cards. Here Card has a sensible default value, and subclasses override it.sys.MAXSIZE crashes, because the constant is sys.maxsize. Here the score doesn't need a sentinel at all.possible_scores() and shuffle() are where the interesting logic lives, and they're the easiest to leave as stubs. Both are implemented here.self. A method written without self, or one that reads deal_index without self., fails as soon as it's called.is_available flag that dealing sets to false and nothing sets back, the flag and the deck drift apart. Here the deck's deal_index is the only record of what has been dealt, so a card can't be "dealt" and "in the deck" at the same time.This example stacks the deck, putting cards in a known order instead of shuffling, so the result is the same every time it runs. Cards are dealt alternately to the player and the dealer.
S, H, D, C = Suit.SPADES, Suit.HEARTS, Suit.DIAMONDS, Suit.CLUBS
deck = Deck([BlackjackCard(1, S), BlackjackCard(13, H), BlackjackCard(6, C),
BlackjackCard(4, D), BlackjackCard(9, D), BlackjackCard(5, S),
BlackjackCard(12, C)])
player, dealer = BlackjackHand(), BlackjackHand()
for _ in range(2): # deal alternately: player, dealer
player.add_card(deck.deal_card())
dealer.add_card(deck.deal_card())
player.add_card(deck.deal_card()) # the player hits on soft 17
while dealer.score() < 17: # the dealer draws to 17 or more
dealer.add_card(deck.deal_card())
[7, 17]. The best one at or under 21 is 17, and since that counts the ace as 11, is_soft() is true. This is a soft 17.[16, 26]. 26 is over 21, so the score is 16, and the ace has dropped back to 1. The hand is no longer soft. The player didn't bust, which is why hitting a soft hand is safe.remaining_cards() is 1. One more deal_card() returns it, and the next returns None.A few more hands show the edge cases:
| Hand | Possible scores | Score | Soft? | Blackjack? |
|---|---|---|---|---|
| A, K | 11, 21 | 21 | yes | yes |
| 7, 7, 7 | 21 | 21 | no | no (three cards) |
| A, A | 2, 12, 22 | 12 | yes | no |
| A, A, A, A | 4, 14, 24, 34, 44 | 14 | yes | no |
| 10, Q, 5 | 25 | 25 | no | no, bust |
Why the blackjack hand subclasses the generic hand. Adding cards, holding them and printing them are the same in every game. Only scoring differs. Subclassing Hand lets BlackjackHand reuse everything and replace score() alone. A poker hand would be another subclass with its own score(), perhaps ranking pairs and flushes. The alternative is composition: one Hand class that takes a scoring function or "rules" object. Composition is better when the rules can change at run time, for example a casino app that switches between blackjack variants, or when a hand needs rules from two games at once. For a fixed set of games, the subclass is simpler.
Why blackjack cards are a subclass too. BlackjackCard exists so a blackjack card can say what it's worth. An alternative keeps Card game-neutral and puts a card_points(card) function in the blackjack code. That avoids a second card type, at the cost of the deck no longer telling you which game its cards belong to. Both are defensible. The subclass shows the idea the question is testing, and the generic Deck[C] keeps it from leaking into the deck.
How to score aces. There are three common ways:
possible_scores() does.We used the second way because possible_scores() is useful in its own right, for example to display "7 or 17" to a player. We checked that it agrees with the shortcut on every hand of one to six cards.
Tracking dealt cards with an index. Popping cards off the list would also work, but the deck would then need another list to collect the dealt cards before the next shuffle. An index keeps every card in one list and makes "return all cards" a single assignment. A real game also lets players discard cards, and that would call for a separate discard pile.
Immutable cards. Because cards are frozen, two hands can hold the same card object safely, and cards can be stored in sets or used as dictionary keys.
Other games. Poker needs a PokerHand whose score ranks the hand (pair, two pair, straight, flush and so on), and it may want the ace to rank above the king. A PokerCard could override value to make the ace 14. Bridge needs a hand that can be sorted by suit. Neither change touches Deck or Hand.
Jokers and other decks. A deck with jokers needs a card with no suit. Make suit optional, or add a Joker subclass. A 32-card deck that leaves out ranks 2 to 6 only needs a different factory method.
Multiple decks. Casino blackjack is often dealt from a shoe, a box holding several packs shuffled together. For example, the rules Ontario's gaming regulator sets for blackjack at fairs and exhibitions require six decks dealt from a dealing shoe. Deck.standard(BlackjackCard, num_decks=6) builds that 312-card shoe (6 × 52). Duplicate cards are now normal, so any check for "this card was already dealt" must count copies instead of looking for the card itself. The same rules place a plastic cutting card in the stack and require a reshuffle once the cutting card is reached and the hand in progress is finished. In our code that's a cut_index next to deal_index: when deal_index passes it, the game calls shuffle() before the next round.
Fair shuffling with Fisher–Yates. A shuffle is fair when every one of the 52! orders of the deck is equally likely. 52! is about 8.07 × 10^67. The Fisher–Yates shuffle does this. It was first described by Ronald Fisher and Frank Yates in 1938 as a pen-and-paper method. Richard Durstenfeld gave the computer version in 1964, and Donald Knuth popularized it as "Algorithm P". It walks from the last position down to the second. At each position i it picks a random position j from 0 to i, inclusive, and swaps the two. Each position is visited once, so it runs in O(n) time, meaning the work grows in step with the number of cards.
The easy mistake is choosing j from the whole list every time. With n cards that gives n^n equally likely sequences of swaps, and n^n can't be split evenly among the n! orders. For three cards there are 27 sequences and 6 orders. Running all 27 shows three orders coming up 5 times and three coming up 4 times, so some orders are 25% more likely than others. Shuffling three cards 60,000 times with our version gives each of the six orders close to 10,000 times.
Python's random.shuffle. You don't have to write Fisher–Yates yourself in Python. CPython's random.shuffle uses the same loop, from the last index down to 1, swapping with a random index from 0 to i. We wrote our own here to show the algorithm. Two caveats from Python's documentation apply to any shuffle driven by the random module:
random module is deterministic and must not be used for security. For a game with real money, where a player who works out the generator's state could predict the cards, use random.SystemRandom, which draws from the operating system's randomness source. Our Deck accepts any random.Random object, so Deck.standard(rng=random.SystemRandom()) is all it takes.Dealer rules and house variations. The walkthrough's dealer draws until 17. Casinos differ on whether the dealer also draws on a soft 17, so a BlackjackRules object holding settings like this, the number of decks and the blackjack payout keeps the variations out of the hand class.
For more practice, try the call center, parking lot and LRU cache designs.
The hard total, counting both aces as 1, is 1 + 1 + 9 = 11. With two aces there are three possible totals: 11, 21 and 31. The best total at or under 21 is 21, so the score is 21, with one ace counted as 11. The hand is soft, but it isn't a blackjack, because a blackjack has exactly two cards.
Two aces counted as 11 already add up to 22, which is over 21. Any hand with two aces at 11 is bust, and dropping one of them to 1 always gives a lower total. So the best score is the hard total, plus 10 if the hand has an ace and the result stays at 21 or under.
Holding, adding and printing cards are the same in every game, and only scoring differs. The subclass reuses all of that and overrides score(). Choose composition, a single Hand that takes a rules object, when the rules must change at run time or when you need many variants of the same game. Then you swap the rules object without creating new classes.
No. With n cards there are n^n equally likely sequences of swaps, and n^n isn't divisible by n!, so some orders come up more often than others. For three cards there are 27 sequences for 6 orders, and some orders appear 5 times while others appear 4. Fisher–Yates fixes this by choosing the swap position only from the cards not yet placed, which gives exactly n! equally likely outcomes.
The deck keeps all of its cards in one list and a deal_index pointing at the next card to deal. Every card before the index has been dealt. shuffle() sets the index back to 0, which returns every card to the deck, and then shuffles the whole list.
Use random.SystemRandom instead. The default generator is deterministic and Python's documentation says it isn't suitable for security purposes, so someone who works out its state from the cards they've seen could predict the next ones. SystemRandom draws from the operating system's randomness source, which doesn't have that weakness. With our design, that's one argument to Deck.standard().
shuffle, the Mersenne Twister's period, the note on long sequences, and SystemRandom.random.py: the source of Random.shuffle, a short Fisher–Yates loop worth reading.@dataclass(frozen=True) gives Card its constructor, equality, hashing and immutability.Previous: Design a call center · Next: Design a parking lot