Defining Classes and Instance Variables

Nouns in a problem description are candidate classes, and simple values such as suit and value are usually instance variables of a class like Card.

Programming

Reading a Description Like a Designer

Object-oriented design often begins before any code is written. A programmer receives a description of what a system must do, usually in ordinary language, and has to decide which pieces of the system deserve to be classes and which actions belong to those classes as methods. The description is the raw material. Nothing in it is labeled as a class or a method, so the designer has to read it with a specific question in mind: which of these words name things, and which name things that happen?

This article follows that reading process using a card game. The goal is to turn a paragraph of prose into a short list of candidate classes and candidate methods. Those candidates are not final decisions. They are a starting point that a designer refines as the program takes shape.

What do you think happens?

In the sentence 'Cards can be added to and removed from hands,' which words are verbs that could become methods?

Cards and hands
added and removed
can and be
only hands

Reveal answer

Answer:

added and removed

Added and removed are the actions in the sentence, so they are the verbs. Each one suggests a candidate method, addCard() and removeCard(), that belongs to Hand. The nouns in the sentence point toward classes instead.

Scanning the Card Game Nouns

The card game description contains five nouns that could each be represented by a class: game, player, hand, card, and deck. A complete program might give classes to all five. A designer working on a first version does not need to tackle everything at once.

game: a candidate class that may be added later
player: a candidate class that may be added later
hand: a candidate class in the first version
card: a candidate class in the first version
deck: a candidate class in the first version

Key point

Choosing a focused starting set is a deliberate design decision. Leaving game and player for later does not mean they are unimportant; it means the first version concentrates on the classes that are most obviously reusable.

Which Nouns Become Classes

A noun in a problem description is a candidate class. The source focuses first on Card, Hand, and Deck because they are the most obviously reusable. Each one is a kind of thing that the program will need to create and work with more than once, and the designer's job is to notice which nouns carry that kind of weight.

The three starting classes are related by containment. A Deck holds many Cards, and a Hand holds some Cards. The diagram below shows that relationship. Card is the smallest unit, and both Deck and Hand are built from it.

Which class contains which? A Deck holds many Cards and a Hand holds some Cards.

Because Card, Hand, and Deck are separate classes, the same Card class can be used by any part of the program that needs cards. A deck and a hand do not each need their own copy of the card logic. This is the reuse the source has in mind when it calls these classes the most obviously reusable.

Simple Values as Instance Variables

Not every noun becomes a class. Simple values such as suit and value are usually instance variables of a class like Card. An instance variable is a slot inside an object that holds that object's own data. Each Card object has its own suit and its own value.

What does one Card object hold, and how do two different Card objects hold different data?

The two Card objects in the diagram share the same slot names, suit and value, but hold different values. That is what distinguishes an instance variable from a class: the class describes the shape of the data, and each object fills the slots with its own contents.

Definition

An instance variable is a named piece of data stored inside an object, where each object of the class holds its own value for that name.

Tracing the Hand Sentence

The description says cards can be added to and removed from hands. This single sentence produces both a class and methods, and tracing it shows how the procedure works one phrase at a time.

Which words in this sentence become a class name, and which become methods?

Worked example

Turning the Hand Sentence into Design Candidates

Given the sentence 'Cards can be added to and removed from hands,' list the candidate class and candidate methods it suggests.

1
Identify the noun that names a thing
Hands is the noun. It names a thing the program must represent, so it is a candidate class: Hand.
2
Identify the verbs that name actions
Added and removed are the actions. Each one suggests a method that acts on a Hand.
3
Name the methods
Added becomes addCard() and removed becomes removeCard(). Both belong to the Hand class, because a hand is the object they act upon.
4
Note what the cards contribute
Cards are the items passed into these methods. They are already candidates from the card noun, so the sentence reinforces Card rather than creating a new class.

Result

Candidate class: Hand. Candidate methods: addCard() and removeCard(), both on Hand.

Verbs as Instance Methods

Verbs in a problem description are candidate instance methods. Each method belongs to the class of the object it acts upon. The verb describes an action, and the object receiving that action determines which class the method lives in.

1
Deck: the verbs shuffle and dealCard describe what a deck does, so they become methods of Deck.
2
Hand: the verbs addCard and removeCard describe changes to a hand, so they become methods of Hand.
3
Card: the source describes cards as relatively passive, so Card mostly holds information. A program still needs to find out a card's suit and value, which suggests Card should offer methods that report those properties.

Why Card, Hand, and Deck Come First

Card, Hand, and Deck are strong first candidates because they are reusable. The same Card class can serve a deck, a hand, and any other part of a card program. Starting with reusable classes means that the core building blocks are settled early, and later nouns such as game and player can be built on top of them.

Best practice

When deciding whether a noun should be a class, ask whether it is an object that will be created and used in more than one place. When deciding whether something should be an instance variable, ask whether it is a simple value that belongs to one object, such as a suit or a value.

Mistakes When Deciding Classes and Variables

Common mistake
Making every noun a class
What it looks like
Creating a separate class for suit and another for value.
Why it fails
Suit and value are simple values that belong to a single Card. The source treats them as instance variables of Card.
Do this instead
Store suit and value as instance variables inside the Card class.
Common mistake
Putting methods in the wrong class
What it looks like
```
Placing addCard() on Card instead of Hand.
```
Why it fails
A method belongs to the class of the object it acts upon. addCard() changes a hand, so it belongs to Hand.
Do this instead
Assign each verb to the class of the object it changes or reports on.
Common mistake
Treating the first list as final
Why it fails
The source states that candidate lists are starting points and more methods will be discovered as the design develops.
Common mistake
Trying to model every noun at once
Why it fails
A focused first version can start with Card, Hand, and Deck. Game and player can be added later.

Practice Mapping a New Description

MEDIUM

A library system is described as follows: 'Members borrow books. Each book has a title and an author. Books can be checked out and returned.' Identify the candidate classes from the nouns, the instance variables from the simple values, and the candidate methods from the verbs.

Hints

Nouns that name things the program must represent are candidate classes, such as Member or Book.
Simple values that belong to one object, such as title and author, are candidate instance variables.
Verbs describe actions, such as checkOut or return, and belong to the class of the object they act upon.

Your attempt (not saved)

Key Takeaways

Nouns in a problem description are candidate classes, and the first version can focus on the most reusable ones such as Card, Hand, and Deck.
Simple values such as suit and value are usually instance variables of a class like Card, and each object holds its own values.
Verbs are candidate instance methods, and each method belongs to the class of the object it acts upon, such as shuffle and dealCard for Deck or addCard and removeCard for Hand.
Candidate lists are starting points; the designer should expect to discover more methods as the design develops.