Documenting Complicated Programs

Brian Bauer

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


Formal (mathematical) documentation of programs, using the methods proposed by Parnas et al. in [41], [30], and [40], has been used in a variety of projects. Most notable among them is the inspection of the shut-down software for the Darlington Nuclear Generating Station [37]. Unfortunately, there are still few examples to use as models for composing new documentation. Programmers and software engineers are still struggling to document certain kinds of programs, because too much invention is required on their part when documenting programs unlike those done in published examples of the method. Typically, the programs that practitioners find difficult are those that use: dynamic memory allocation, input and output, recursive invocation of programs, and message passing.

In order to address the lack of available examples, this thesis provides a number of illustrative documentation examples.