Writing Class Header Descriptions

The class description must give a complete, thorough description of the abstraction being modeled using terms from the problem domain. This section is very important to the readers of your design, so clear writing matters. This section will be lengthy unless the abstraction is a common abstraction like a queue or list. This section belongs in the javadoc class comment.

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.


Example

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.



Example

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.




CPE 308 Home