Aspects of internal program documentation-an elucidative perspective

Abstract

It is difficult and challenging to comprehend the internal aspects of a program. The internal aspects are seen as contrasts to end user aspects and interface aspects. Internal program documentation is relevant for almost any kind of software. The internal program documentation represents the original as well as the accumulated understanding of the program, which is very difficult to extract from the source program and its modifications over time. Elucidative programming is a documentation technique that was originally inspired by literate programming. As an important difference between the two, elucidative programming does not call for any reorganization of the source programs, as required by literate programming tools. Elucidative programming provides for mutual navigation in between program source files and sections of the documentation. The navigation takes place in an Internet browser applying a two-framed layout. In this paper we investigate the applicability of elucidative programming in a number of areas related to internal program documentation. It is concluded that elucidative programming can solve a number of concrete problems in the areas of program tutorials, frameworks, and program reviews. In addition we see positive impacts of elucidative programming in the area of programming education.