Literate programming

Wikipedia, as of June 2006, introduces the concept of literate programming in the following way:

"Literate programming is the writing of computer programs primarily for human beings to read, similar to a work of literature; hence the name 'literate programming.' This contrasts with the traditional view that a programmer's primary creation is source code to be read by a computer. Documentation and source code are written into one source file. Both the complete source code and its documentation can be extracted from this file with specific utilities. The information is written and presented in a reading order suitable for human consumption with detailed explanations. The code is automatically rearranged for ordinary processing by other computer tools, such as compilers or interpreters."

Personally, I very much like the following quotes by Donald Knuth (who together with Silvio Levy originally formulated the philosophy behind literate programming) on his point-of-view on the WEB language, also cited in the introduction on

"I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: `Literate Programming.'

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other."

[Donald Knuth, ``Literate Programming'', in Literate Programming (CSLI Lecture Notes, Stanford, 1992)]

One particular dialect of literate programming languages is CWEB, which specifically targets traditional C as the language of choice. Again quoting Donald Knuth, CWEB can be summarized as

"The philosophy behind CWEB is that an experienced system programmer, who wants to provide the best possible documentation of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately.

The structure of a software program may be thought of as a `WEB' that is made up of many interconnected pieces. To document such a program we want to explain each individual part of the web and how it relates to its neighbors. The typographic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages like C make it possible for us to specify the algorithms formally and unambiguously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation.

Besides providing a documentation tool, CWEB enhances the C language by providing the ability to permute pieces of the program text, so that a large system can be understood entirely in terms of small sections and their local interrelationships. The CTANGLE program is so named because it takes a given web and moves the sections from their web structure into the order required by C; the advantage of programming in CWEB is that the algorithms can be expressed in ``untangled'' form, with each section explained separately. The CWEAVE program is so named because it takes a given web and intertwines the TeX and C portions contained in each section, then it knits the whole fabric into a structured document."

[Donald Knuth, The CWEB System of Structured Documentation (Addison-Wesley, Massachusetts, 1994)]

Return to previous page

Leave a message

Your name:

Your email: (required)


Generated by ::emailform::

Last modified Wednesday 15 Feb 2023