Documentation Paradigms - A Progres Report

Mr. Michal Iglewski

Dr. Jan Madey

Dr. David Lorge Parnas

Mr. Philip Kelly

Software Engineering Research Group
CRL, McMaster University,
Hamilton, Ontario, Canada L8S 4K1


This paper illustrates two of the computer systems documents discussed in [11]. A module interface specification treats the module as a black-box, identifying all module's access-programs (i.e. programs that can be invoked from outside the module), and describing their externally visible effects. The interface is documented by the trace assertion method [9]. A module internal design document, one for each implementation of the module, describes the module's (internal) data structure, the intended interpretation of that data structure (in terms of the module interface), and the effect of each access-program on the module's data structure. Program effect is described by a mapping from a set of data states before program execution to a set of data states after program execution. This mapping is expressed by LD-relations [7,13].

We illustrate these documents by presenting a few modules which were specified, designed, implemented, and tested within the Table Tool Project [15].

The paper contains also a sample implementation of these modules based on the module internal design document. The accompanying paper [1] describes the way this implementation was tested against the module interface specification.