[an error occurred while processing this directive]

Instructions for Client Specifications

Introduction

The module client specifications are the final product of the early design phase for the module. These specifications contain the following sections. For some modules, 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 module. You should aim for a module that be easily used and understood without having to understand the implementation.

Purpose

The objective of this section is to assist a specifications user who is browsing for a module 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 module plays.

Client Data Model

This is an important section. Try to give the user a mental image of the structure of the data managed by the module and how the functions are used to manipulate the data. When functions are mentioned, you can put in HTML links to the function specifications below. This is a good place to define terms that are used in later sections. The model you present should be free of implementation-dependent concepts.

If the module maintains some internal state that the client needs to be aware of, it should be mentioned here. For example, most input processing modules keep track of current position in the input. Many errors in the use of input processing modules arise from imprecise specification of when the current position is advanced. Be sure to mention functions that need to be called before the internal state is meaningful. For input processing modules, the current position may not be meaningful until a client has called one of the module functions.

If there are limitations and restrictions on the use of the module they should be mentioned towards the end of this section. This is also a good place to indicate error handling policies.

Importing Information

For C programming, the use of a module usually requires including header files in client source code files. This section should show the includes that are needed. If multiple includes are needed the order may be important. If so, that should be noted here. Order requirements usually arise when one header file has type or function declarations uses types that are declared in a second header file. Then the second header file must be included first.

Although the information in this section is important client information, it may depend on implementation decisions about the breakdown of the module into submodules and the determination of other modules that are used by this module. You may have to wait until you have done some preliminary work on implementation specifications before filling this in.

Public Data Types

This section should briefly describe the data types that are introduced in the module. Only mention data types that the client needs to work with. The names for public data types should not contain implementation information. Use names that are meaningful to the client.

If you return a complex data type (or a pointer to a complex data type) then the client should be able to use functions to get at individual parts of the data. You can either document those functions as part of this module or document them as a separate module.

Public Functions

This section should contain precise specifications for each function that is intended for use by a client. It can be helpful to divide the functions into categories of related functions.

Clarity, precision, and conciseness are important qualities to consider here. These quality factors are dependent on the design of the functions as well as the words that you use to describe them. You should spend considerable time working on the design before writing these specifications. See Developing Client Interfaces with Communication Simulations for a methodology for developing your design.

You can often make function specifications clear and concise without sacrificing precision by using concepts defined in the Client Data Model section.

If you find that you cannot precisely specify a function in a few sentences then you are probably trying to do too much with it - it is incohesive. Reevaluate the function to see if it can be broken up into more primitive functions.

You can often make function 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 function specifications then introduce terminology in the Client Data Model section to simplify the repetion.

When appropriate, be sure to specify carefully whether return values are shared references or distinct copies. For example, suppose a module returns character strings. The module could either be returning a shared reference to a single character array variable that is used over and over with different contents or it could return a distinct dynamically allocated copy for each call. If the strings are to be used as keys in a lookup table then the client needs distinct copies. Otherwise, all keys end up refering to the same string.

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

Examples

[an error occurred while processing this directive]