Incremental redocumentation using literate programming

Abstract

The primary aim of this research is to investigate means of improving program comprehension through redocumentation. In particular it will concentrate on using Literate Programming as a method for program redocumentation. Documentation is crucially important as an aid to understanding software systems. The Incremental Redocumentation Using Literate Programming System analyses the existing source code and merges in a range of other information, in order to create a complete documentation package. This may include not only traditional paper documents, but also hypertext facilities, animated specifications and output from other analysis tools. The status of the documentation is implicitly elevated to that of an integral part of the system, rather than an optional extra. Where a configuration management system is used to manage different versions of a system, the documentation can also be brought under its control. The literate programming paradigm provides the encouragement and capability to produce high quality code and documentation simultaneously. Conceptually, literate programming systems are document preparation systems. The primary goal of a literate program is to be understandable to the programmers who are going to have to read it at some later date - often while involved in maintenance, or perhaps when trying to determine the possibility of reusing parts of the code for later projects. This thesis presents a structures of C programs and literate C programs, and describes the features of captured literate C programs. A method of the capture process and also the functions of the redocumentation process are described. In addition, this thesis outlines how the individual stages in the capture process and the edit process are used to redocument a C program. The results of application of the process are highlighted by way of example programs. The evaluation process is performed by comparing the results of an existing literate program with those resulting from the application of the method described within this thesis. The results have shown that the captured redocumented literate C program is more readable and understandable than source code only, and that it provides a basis for subsequent maintenance and further redocumentation.