Documentation centered approaches

Documentation is often considered a poor source of information for program maintenance. Matainers suggest that it is frequently misleading or wrong, or does not provide the required in-formation. However, even when \good" documentation is available, it is not the primary source of information about a program. One survey found that the time spent studying code was 3.5 times that spend studying documentation [Fjeldstrad and Hamlen 83], even though the available documentation was of high quality.

Current program comprehension tools allow the user to generate documentation that is con-sistent with the techniques (e.g., data ows, control ows, etc.) available in the tool. While the tools can no doubt produce reams of information, it is not clear what additional value (beyond that provided by the tool display) this documentation has, since it can all be reproduced by the tool at any point. In addition, when using the tool on-line (as opposed to documents produced by the

CHAPTER 7. A MAINTENANCE PERSPECTIVE 105 tool), the user is assured of consistency with the source code.

In addition to producing hard copy, new program comprehension tools often allow the forging of links between source code and documents. An illustrative example is the ParaSET workbench, which allows the user to create three types of links between code and documentation: hypertext links which allow forward and backward navigation, \soft" associations which spawn warnings when documents have become inconsistent with source, and \hard" associations which force consistency between documents and source for constructs like tokens and identiers. ParaSET also supports the forging of links between source and other related information, such as regression tests.

Linking of source and related information can potentially be quite useful for supporting program comprehension, particularly for connecting domain information with source manifestations. The value of the support obviously depends on the quality of the information connected, the links built, and the willingness of personnel to build and maintain the links. Ideally, developers would construct the links as the application is built, and maintainers would use and update these links as appropriate. This, however, requires that both developers and maintainers are willing to use the workbench, and that the workbench is appropriate for both tasks.

Research involving document-centered approaches has focused on improved document organi-zation, content and access to information. [Pinto and Soloway 88] focused their work on supporting an \as needed" strategy toward program comprehension (i.e., learn that portion of the application necessary to make the expected modication). The authors approach was to design a documenta-tion format that explicitly documented the causal reladocumenta-tionships between non-connected sequences of source code. In eect, their documentation format ignores much of the intervening detail and explicitly documents the purpose, structure and eect of the basic algorithm within the program (as opposed to providing this information in a separate document).

Pinto and Soloway tested their approach on a small group of subjects, and reached the conclusion that such documentation formats helped programmers who were not experienced with the type of application processing represented in the program. On the other hand, more experienced personnel seemed to gain little from the \improved" documentation format, presumably because they needed little help from any documentation to discern the basic algorithm of the application.

[Oman and Cook 90] suggested that software documents should be structured according to the \Book" paradigm. This paradigm uses a book metaphor (preface, table of contents, chapters, sections, paragraphs, etc.) for organizing source code to allow quicker and better program com-prehension. Prototype tools were developed to reformat existing source code listings into the book format, without aecting the compilation of the code. A series of empirical studies were performed using this format to assist maintenance activities. Results of these studies indicated that the book

CHAPTER 7. A MAINTENANCE PERSPECTIVE 106 paradigm provided a very signicant improvement in computer student's abilities to enhance a program by adding a module, and also reduced the time (by 28%) for professional programmers to comprehend a more complex program and construct appropriate call graphs. Furthermore, the professionals using the book format were more accurate that those using traditional code listings.

The authors suggest development of a hypertext viewing tool as a way to improve programmers performance even more.

Other approaches to improving the accessibility of documentation have also been attempted, including: automatic generation of hypertext between documentation and source code [Jawre 92], [Sarre 92] and [Brade 94], and embedding markup languages like SGML in program code to embed information about semantics and design [Cowan 94].

An alternative approach that should be mentioned involves providing more complete documen-tation in the form of \design records" [Salasin 92]. A design record is a collection of information (often on-line) to support the information needs of both software developers and maintainers.

This information captures design decisions, supports (preferably interactive) browsing, and pro-vides traceability of requirements, artifacts, and decisions. A primary aim of a design record is to improve the speed and accuracy of program comprehension. Among the potential sources of infor-mation for a design record are unit development folders, system development journals maintained by developers, project databases, conguration management systems, life cycle information, data and process models, reverse engineering, and system evolution records [Arnold 93].

[Abbattista 94] attempted to identify the impact of the use of design records on software main-tenance. The authors found that for measures of the completeness and accuracy on an impact analysis task, students do slightly better when assisted by design records as opposed to \standard"

documentation techniques. However, the time required by the students was slightly increased when supported by design records. The authors in part attribute the only moderate improvement to lack of tool support to help students handle the increased volume of information with design records.

Unfortunately, it is not clear that more inclusive documentation or improved formats will provide a signicant benet to maintenance personnel. In private conversations, the CASE Environments project has identied organizations where the original documentation is ignored when the software is delivered. Among the rst eorts commonly undertaken is the complete re-documentation the program based on a systematic study of the source code, undertaken by the person or people who will be maintaining that code.

These organizations nd this to be a particularly eective way to prepare for subsequent code maintenance tasks. Unfortunately, these same organizations have also found that they must repeat the activity whenever a new person takes over maintenance. Even the documentation produced by

CHAPTER 7. A MAINTENANCE PERSPECTIVE 107 an experienced maintainer (which we would expect to be particularly useful for other maintainers) is not adequate for another maintainer. This suggests that it may be the process of documen-tation, and not the actual document produced, that supports the individual in the task of code comprehension.