[an error occurred while processing this directive]

Writing Client Specifications


The class client specifications are the final product of the client-oriented design phase for the class. These specifications contain the following sections. 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.


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

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.

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.

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.

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.


[an error occurred while processing this directive]