[an error occurred while processing this directive]

Writing Client Specifications

Introduction

The class client specifications are the final product of the client-oriented design phase for the class. These specifications contain the following sections.

Purpose
Superclass and Interfaces
Importing Information
Client Data Model
Public Methods

For some classes, you may want to add sections that deal with information that does not fall into these categories.

The concepts of cohesion and coupling are important consideration in the design of a class. You should aim for a class that be easily used and understood without having to understand the implementation. Good design and good documentation are both necessary to acheive this goal.

Purpose

The objective of this section is to assist a specifications user who is browsing for a class that they need to work with. The user may be

looking for a class that provides services needed for implementing a different class, or
trying to determine where changes are needed for maintenance, or
trying to find a class that can be reused in a new program.

This section should be brief. Consider the following questions. From the answers, select a few sentences that serve best to help a programmer identify the kind of role that the class plays.

What needs does the class fulfill?
What is the purpose of the class or its objects?
What are the responsibilities of the class and its objects?
What is the functionality of its objects?
What kind of information do its objects deal with?

Superclass and Interfaces

This section should provide links to the client documentation for the superclass of this class and for all interfaces that this class implements, except when the superclass is class Object.

For Java programming, a class can extend one other class, which is called its superclass. A class may also implement any number of interfaces. To avoid duplication of information and the resulting maintenance headaches, the documentation for a class usually only describes new features and new behavior added by the class to features inherited from the superclass or interfaces. Then client specification readers will need links to the superclass and interface documentation.

Importing Information

When you are writing code for a class, it will often play the role of a client for another class, which plays the role of a server class. The Importing Information section for the server class should show all of the import statements that the client code needs to use the server class.

Client Data Model

This is an important section. Its objective is to present a mental image of how the class and its objects are used to meet the clients needs. When writing this section, put yourself in the client's shoes. Start by thinking in terms of the needs of the client, gradually refining those needs into use cases. This is a good place to define terms that are used in method specifications.

The model that you present should not contain implementation-dependent concepts. When methods are mentioned in the client data model, you can put in HTML links to the method specifications below.

Here are some questions to consider when describing the client data model.

How is an object created?
In Java, special methods called constructors are used to create objects. A class can have any number of constructors, each with different parameter types. The constructors can contain code to initialize data features of objects in the class.
Achieving data integrity requires a coordination between constructors and other methods. The constructors have the responsibility of creating objects that meet data integrity constraints. Other methods must be designed to maintain the constraints.
What are the attributes of an object?
An attribute is simple data that the client needs to access, such as the balance for a checking account object, the amount of a check object, or the name of a person object.
A class will often provide getter and/or setter methods for each object attribute. A getter returns the value of an attribute and a setter sets its value. If it is desirable to make an attribute read only or its value is computed from other object attributes then its setter should be omitted. For consistency, is is best to use the names getAttribute for getter methods and setAttribute for setter methods, where Attribute is the name of the attribute with its first letter capitalized.
What relationships between an object of this class and other objects are important for the client.
Take care with this question. If you start thinking too early about how the class will be implemented, you will often create new classes to aid with the work of this class. The relationship of collaboration is important in object-oriented design, but you need to ask yourself if a client needs to be aware of it. If so, it should be mentioned here. If not, make a note of the relationship, but save it for implementation documentation.
What kind of implicit state information does an object maintain on behalf of a client?
State information refers to information about an object that is required in order to understand the behavior of an object but is not directly accessible. For example, the position for a file or iterator object and the contents of a table object are state information.

The following questions should also be considered. It is usually easier to understand a client data model if these questions are dealt with as separate concerns.

What kind of limitations and constraints does the class impose on its objects?
Classes often need to impose constraints on objects in order to ensure data integrity. In the design-by-contract methodology [Meyer92a] these constraints take the form of method preconditions and object invariants. The invariants are maintained by internal code, but the preconditions are imposed on the client. Thus preconditions are an important part of the client model.
How does the class deal with errors?
Documentation for a class is not complete without a description of method behavior when preconditions are not met. There are occasions when methods need not make any effort to handle these errors, but it is usually best to terminate the program with an error message that indicates the nature of the error. In Java, and many other object-oriented languages, there is an exception mechanism for dealing with the errors. When preconditions are violated, the method can throw an exception.
An exception will generate an error message and terminate the program unless some method in the current active chain of calls catches the exception. This results in a flexible mechanism for handling errors - the server detects the error, but is not forced to handle the error by itself. Clients, direct or indirect, can intervene,, allowing the decision of how to handle the error to be made at a level where more context is available.
It is extremely useful for a method to check if its preconditions are met and to throw an exception if the preconditions are violated. The primary reason for this is that clients make mistakes, calling methods incorrectly. The clients will get much better fedback about an error if the server immediately thows an exception. Otherwise, symptoms of the error may not appear until much later, when it is no longer clear what component is causing the problem.
The client usually makes no attempt to catch precondition violation exceptions, so that the program terminates with an error message. This error message is not intended for viewing by the users of a program. It is a sanity check that informs writers of client code that there is a problem.
When the client is testing software, it may be desirable to catch precondition violation exceptions. For test software it is often useful to be able to continue the testing in spite of errors.
Sometimes, when run time is an important consideration, precondition violation checks may be omitted from the production version of software. Even then, it is usually best to include the checks during development.

Public Methods

This section should contain precise specifications for each method that is intended for use by a client. These methods are usually declared as public in Java. Clarity, precision, and conciseness are important qualities to consider in this section. When writing the method specifications, put yourself in the clients shoes. Describe what the method is doing rather than how it is doing it. It can be helpful to divide the methods into categories of related methods.

The quality of method specifications is dependent on the design of the methods as well as the words that you use to describe them. You should spend considerable time working on the design before writing the specifications. Before filling out this section, you may find it easier to work with index cards for your methods.

Pay particular attention to cohesion. If you find that you cannot precisely specify a method in a sentence or two then you are probably trying to do too much with it. Reevaluate it to see if it can be broken up into more primitive methods.

You can often make method specifications clear and concise without sacrificing precision by using concepts defined in the Client Data Model section. If you find that there are repeated lengthy phrases in the method specifications then introduce terminology in the Client Data Model section to simplify the repetion.

Your class may have methods that are intended for internal use. These methods should not be mentioned here. They will be included in the class implementation specifications.

Examples

[an error occurred while processing this directive]