Guidelines
Your description of the abstraction being modeled includes three
parts:
Elements: the domain values. If your class is a collection, what kind
of things does it contain?
Structure: how the data is organized, e.g., linear, circular,
tree, record (or aggregate).
Operations: the operations that can be performed on the data.
Start your definition with
"The X class represents ... "
"The X class models ... "
"An X is a ... "
Don't start your definition with
"The X class handles ..."
"The X class is responsible for ..."
"The X class is used to ... "
"This class holds ... "
Don't use circular definitions:
Bad: "The Auto class represents an automobile."
Bad: "The Auto class allows for creating and manipulating an
auto."
I still don't know what an X is.
Better: "The Auto class models a powered, wheeled vehicle for
individual
or small group transportation..."
Bad: "The FileManager class is used to read lines of text from a
flat
file."
Better: "The TextFile class represents a collection of records
(physical
lines) in a standard ASCII text file in persistent storage. A
TextFile
has a name, size (number of physical lines), and a last access
date.
A TextFile can be read from storage and can be iterated over to obtain
the individual lines."
Provide a definition of what the thing is in the problem domain, not
a list of its data attributes in the design.
Bad: "The Player class stores a player's name, score, and the
key they press to ring in when playing a multiplayer game."
Better: "A Player is a person who is participating in the game.
Each player is identified by their name. A Player's score represents
how
many points they've earned so far. Each player chooses a particular
keyboard
character to request attention during competitive play."
Make sure the description is accurate and correct.
Bad: Professors are employees of the university who teach classes.
This is incorrect. Lecturers also teach classes.
Don't confuse elemental items with collections.
If the class is a collection, make sure the name sounds like a
collection
(e.g. "EmployeeList").
Don't provide any implementation details.
Bad: "Employee contains a String name." Better: "An
Employee
has a name."
Bad: "Week is an array of seven days." Better: "A week
contains seven days."
Refer to the Case Studies for examples.
The Airplane class models a powered, winged vehicle that provides
air
transportation. An airplane has an FAA license number which
uniquely
identifies it. An airplane may carry crew, passengers, and cargo.
An airplane has a maximum allowed load weight which is a function of
number of crew, passengers, and cargo weight. An airplane may be
private or commercial.
Operations:
An airplane can be assigned values for crew, passengers, and cargo
weight.
An airplane can determine if its load weight has exceeded its allowed
limit.
An airplane can compute the runway distance needed for it to takeoff.
An airplane can report its license number and whether it is private or
commercial.
ListOfSkills represents an unordered collection of the job skills an
employee possesses. While most employees may be skilled at only
one
job, experienced employees may have acquired the skills to perform
several
jobs. Duplicate skills aren't allowed.
Operations:
Employees can have new skills added to their list, or in rare
situations
removed from their list.
The list can be queried to determine if an employee possesses
a given skill.
The list can report how many skills it contains.
The list can report the names of all the skills it contains.