Incremental redocumentation using literate programming

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

Documentation for software maintenance and there documentation of existing systems

The importance of software documentation in maintenance work is widely acknowledged by those involved in the work. However, many new software projects axe still being produced with documentation that is inadequate for efficient support of the product following development. When a product enters the maintenance phase of its life-cycle, the need for quality documentation increases dramatically as it is common for the maintenance team to be composed of personnel who were not involved in the products development. This thesis surveys the tools available for supporting the production of software documentation and then proposes a tool, based on hypertext technology, that will enable maintenance programmers to efficiently create documentation about systems they are working on, where the existing documentation is unsatisfactory

Software maintenance: redocumentation of existing Cobol systems using hypertext technology

One of the major problems associated with the maintenance of existing software systems is their lack of documentation. This can make very large, poorly structured programs very difficult to maintain. Nearly all traditional documentation tools are either designed for use in the development stage of the software lifecycle or are report generators such as cross reference generators. The problems of lack of documentation are compounded when applied to third party software maintenance as the staffs are often initially unfamiliar with the code they are maintaining. This thesis describes these problems in detail and evaluates the feasibility of a tool to help with redocumentation based on current hypertext technology

A software maintenance method based on the software configuration management discipline

Software maintenance has until recently been the neglected phase in the software engineering process, despite the fact that maintenance of existing software systems may account for over half of all efforts expended by a software organization. Research into software maintenance, compared to other phases of the software engineering process is rare. Moreover, it is widely accepted that current software maintenance methods and techniques are unable to cope with the complexity inherent in maintaining software systems. This thesis is concerned with the development of a method, named Configuration Management Formalization for Maintenance (COMFORM), designed for the maintenance of existing software systems. COMFORM provides guidelines and procedures for carrying out a variety of activities performed during software maintenance. It accommodates a change control framework, around which the Software Configuration Management discipline is applied. Redocumentation is another problem tackled by COMFORM, which gathers together the documentation necessary to improve the maintainability and quality of existing software systems. This is achieved by the use of forms representing the output of each phase of a proposed software maintenance model. The information obtained by filling in forms is formalized according to a data model, which provides a common basis for the representation of the method's functionality. Finally, a prototype of COMFORM has been implemented, so that the procedures and guidelines set up by the method can be enforced and followed by its users

The development of a program analysis environment for Ada: Reverse engineering tools for Ada

The Graphical Representations of Algorithms, Structures, and Processes for Ada (GRASP/Ada) has successfully created and prototyped a new algorithm level graphical representation for Ada software, the Control Structure Diagram (CSD). The primary impetus for creation of the CSD was to improve the comprehension efficiency of Ada software and thus improve reliability and reduce costs. The emphasis was on the automatic generation of the CSD from Ada source code to support reverse engineering and maintenance. The CSD has the potential to replace traditional prettyprinted Ada source code. In Phase 1 of the GRASP/Ada project, the CSD graphical constructs were created and applied manually to several small Ada programs. A prototype (Version 1) was designed and implemented using FLEX and BISON running under the Virtual Memory System (VMS) on a VAX 11-780. In Phase 2, the prototype was improved and ported to the Sun 4 platform under UNIX. A user interface was designed and partially implemented. The prototype was applied successfully to numerous Ada programs ranging in size from several hundred to several thousand lines of source code. In Phase 3 of the project, the prototype was prepared for limited distribution (GRASP/Ada Version 3.0) to facilitate evaluation. The user interface was extensively reworked. The current prototype provides the capability for the user to generate CSD from Ada source code in a reverse engineering mode with a level of flexibility suitable for practical application

Inverse software configuration management

Software systems are playing an increasingly important role in almost every aspect of today’s society such that they impact on our businesses, industry, leisure, health and safety. Many of these systems are extremely large and complex and depend upon the correct interaction of many hundreds or even thousands of heterogeneous components. Commensurate with this increased reliance on software is the need for high quality products that meet customer expectations, perform reliably and which can be cost-effectively and safely maintained. Techniques such as software configuration management have proved to be invaluable during the development process to ensure that this is the case. However, there are a very large number of legacy systems which were not developed under controlled conditions, but which still, need to be maintained due to the heavy investment incorporated within them. Such systems are characterised by extremely high program comprehension overheads and the probability that new errors will be introduced during the maintenance process often with serious consequences. To address the issues concerning maintenance of legacy systems this thesis has defined and developed a new process and associated maintenance model, Inverse Software Configuration Management (ISCM). This model centres on a layered approach to the program comprehension process through the definition of a number of software configuration abstractions. This information together with the set of rules for reclaiming the information is stored within an Extensible System Information Base (ESIB) via, die definition of a Programming-in-the- Environment (PITE) language, the Inverse Configuration Description Language (ICDL). In order to assist the application of the ISCM process across a wide range of software applications and system architectures, die PISCES (Proforma Identification Scheme for Configurations of Existing Systems) method has been developed as a series of defined procedures and guidelines. To underpin the method and to offer a user-friendly interface to the process a series of templates, the Proforma Increasing Complexity Series (PICS) has been developed. To enable the useful employment of these techniques on large-scale systems, the subject of automation has been addressed through the development of a flexible meta-CASE environment, the PISCES M4 (MultiMedia Maintenance Manager) system. Of particular interest within this environment is the provision of a multimedia user interface (MUI) to die maintenance process. As a means of evaluating the PISCES method and to provide feedback into die ISCM process a number of practical applications have been modelled. In summary, this research has considered a number of concepts some of which are innovative in themselves, others of which are used in an innovative manner. In combination these concepts may be considered to considerably advance the knowledge and understanding of die comprehension process during the maintenance of legacy software systems. A number of publications have already resulted from the research and several more are in preparation. Additionally a number of areas for further study have been identified some of which are already underway as funded research and development projects

A combined representation for the maintenance of C programs

A programmer wishing to make a change to a piece of code must first gain a full understanding of the behaviours and functionality involved. This process of program comprehension is difficult and time consuming, and often hindered by the absence of useful program documentation. Where documentation is absent, static analysis techniques are often employed to gather programming level information in the form of data and control flow relationships, directly from the source code itself. Software maintenance environments are created by grouping together a number of different static analysis tools such as program sheers, call graph builders and data flow analysis tools, providing a maintainer with a selection of 'views' of the subject code. However, each analysis tool often requires its own intermediate program representation (IPR). For example, an environment comprising five tools may require five different IPRs, giving repetition of information and inefficient use of storage space. A solution to this problem is to develop a single combined representation which contains all the program relationships required to present a maintainer with each required code view. The research presented in this thesis describes the Combined C Graph (CCG), a dependence-based representation for C programs from which a maintainer is able to construct data and control dependence views, interprocedural control flow views, program slices and ripple analyses. The CCG extends earlier dependence-based program representations, introducing language features such as expressions with embedded side effects and control flows, value returning functions, pointer variables, pointer parameters, array variables and structure variables. Algorithms for the construction of the CCG are described and the feasibility of the CCG demonstrated by means of a C/Prolog based prototype implementation

GRASP/Ada: Graphical Representations of Algorithms, Structures, and Processes for Ada. The development of a program analysis environment for Ada: Reverse engineering tools for Ada, task 2, phase 3

The main objective is the investigation, formulation, and generation of graphical representations of algorithms, structures, and processes for Ada (GRASP/Ada). The presented task, in which various graphical representations that can be extracted or generated from source code are described and categorized, is focused on reverse engineering. The following subject areas are covered: the system model; control structure diagram generator; object oriented design diagram generator; user interface; and the GRASP library

GRASP/Ada (Graphical Representations of Algorithms, Structures, and Processes for Ada): The development of a program analysis environment for Ada. Reverse engineering tools for Ada, task 1, phase 2

The study, formulation, and generation of structures for Ada (GRASP/Ada) are discussed in this second phase report of a three phase effort. Various graphical representations that can be extracted or generated from source code are described and categorized with focus on reverse engineering. The overall goal is to provide the foundation for a CASE (computer-aided software design) environment in which reverse engineering and forward engineering (development) are tightly coupled. Emphasis is on a subset of architectural diagrams that can be generated automatically from source code with the control structure diagram (CSD) included for completeness