[PDF][PDF] Literate programming

CJ Van Wyk - Communications of the ACM, 1989 - dl.acm.org
CJ Van Wyk
Communications of the ACM, 1989dl.acm.org
The program is written in the C language, a. nd is internally documented in the concise and
precise manner which is appropriate to real programs. Although some writers find this form
too terse and stylized for the purposes of presentation, I believe they do a disservice. A
textbook, and a useful program, simply have different purposes. For example, a program
which is “explained” at considerable length, may in fact be poorly documented-from the
viewpoint of a person wishing to know some quite reasonable postcondition of a certain …
The program is written in the C language, a. nd is internally documented in the concise and precise manner which is appropriate to real programs. Although some writers find this form too terse and stylized for the purposes of presentation, I believe they do a disservice. A textbook, and a useful program, simply have different purposes. For example, a program which is “explained” at considerable length, may in fact be poorly documented-from the viewpoint of a person wishing to know some quite reasonable postcondition of a certain procedure. This column should not be taken as a “literate program,” in Knuth’s restricted sense. This is a column about the program, but the program itself is suitable for posting (without explanat. ion) on Usenet. If space allowed, the program would have been presented in its entirety (rather than as fragments), along with a machine-generated index. The lack of innovation in this column should not be taken as an argument against progress. Instead, it is hoped to be a demonstration of the manner in which a traditional program can be kept both precise and manageable. It should be noted that the reduced program is about TOO lines long, of which about 300 are comments and spaces. Although the program was adjusted for publication, it was not fluffed; this is indeed a real program, written for real use, in accordance with standards based on maintenance experience. The specification was the first part of the program to be written. This was kept up to date as the program evolved, and is as illustrated in Figure 1. Figure 1 coniains the program’s identification, a standard copyright notice, and a functional specification. In most cases, the front of a real program contains other material. For example, well-maintained programs contain a history log, showing the dates of revisions, the names of the parties involved, and short explanations of the revisions. This is usually done according to some standard format (eg, labelled columns, or an indentation style) and the major asset of any such format is the imposed uniformity. A virtue of keeping the log prominent is
ACM Digital Library