documentation of program code

Computer system documentation can be divided into two main categories based upon the intended audience. Manu-als and training materials for users focus on explaining how to use the program’s features to meet the user’s needs (see documentation, user). This entry, however, focuses on the creation of documentation for programmers and oth-ers involved in software development and maintenance (see also technical writing).

Software documentation can consist of comments describing the operation of a line or section of code. Early programming with its reliance on punched cards had only minimal facilities for incorporating comments. (Some of the proponents of COBOL thought that the language’s English-like syntax would make additional documentation unnec-essary. Like the similar claim that trained programmers would no longer be needed, the reality proved otherwise.)

After the switch from punchcard input to the use of keyboards, adding comments became easier. For example, a comment in C looks like this:

printf(“Hello, world\n”);

/* Display the traditional message */

while C++ uses comments in this form:

cout << “Hello, World”;

// This is also a comment

Each language provides a particular symbol or set of sym-bols for separating comments from executable code. The compiler ignores comments when compiling the program.

While proper commenting can help people understand a program’s functions, the coding style should also be one that promotes clarity. This includes the use of descriptive and consistent names for variables and functions. This can also be influenced by the conventions of the operating sys-tem: For example, Windows has many special data struc-tures that should be used consistently.

In addition to the commented source code, external documentation is usually provided. Design documents can range from simple flowcharts or outlines to detailed specifi-cations of the program’s purpose, structure, and operations. Rather than being considered an afterthought, documenta-tion has been increasingly integrated into the practice of software engineering and the software development process. This practice became more prevalent during the 1960s and 1970s when it became clear that programs were not only becoming larger and more complex, but also that significant programs such as business accounting and inventory appli-cations were likely to have to be maintained or revised for perhaps decades to come. (The lack of adequate documenta-tion of date-related code in programs of this vintage became an acute problem in the late 1990s. See y2k problem.)

Documentation Tools

As programmers began to look toward developing their craft into a more comprehensive discipline, advocates of structured programming placed an increased emphasis not only on proper commenting of code but on the develop-ment of tools that could automatically create certain kinds of documentation from the source code. For example, there are utilities for C, C++, and Java (javadoc) that will extract information about class declarations or interfaces and for-mat them into tables. Most software development environ-ments now include features that cross-reference “symbols” (named variables and other objects). The combination of comments and automatically generated documentation can help with maintaining the program as well as being helpful for creating developer and user manuals.

While programmers retain considerable responsibility for coding standards and documentation, larger program-ming staffs typically have specialists who devote their full time to maintaining documentation. This includes the log-ging of all program change requests and the resulting new distributions or “patches,” the record of testing and retest-ing of program functions, the maintenance of a “version history,” and coordinating with technical writers in the production of revised manuals.