Literate programming

Literate programming is a certain way of writing computer programs which combines documentation and source code into one file. The compilable source code and the formatted documentation can be extracted from this file with specific utilities. The main idea is to regard programs as communications to human beings, as works of literature, hence the name "literate programming". The documentation is organized as a cross-linked web of documented and numbered code sections whose order may differ from the one in the compilable program.

The first published literate programming environment was WEB?, introduced by Donald Knuth in 1981 for his TeX typesetting system; it uses Pascal as its underlying programming language and TeX for typesetting of the documentation. The complete commented TeX source code was published in Knuth's TeXbook. Knuth had internally used a literate programming system called DOC as early as 1979; he was inspired by the ideas of Pierre Arnoul de Marneffe. The free CWEB, written by Knuth and Levy, is WEB adapted for C, C++ and Java, runs on most operating systems and can produce TeX and PDF documentation. Other implementations of the concept are noweb and FunnelWeb.

Less powerful systems to integrate documentation and code are also sometimes labeled literate programming; examples are pod? for perl, doc++? for C/C++/Java and javadoc? for java. These however do not quite follow the literate programming philosophy since they typically just produce documentation about the program, such as specifications of functions and parameters, and not documentation of the program source code itself.

---

See also:

• Donald E. Knuth, Literate Programming, Stanford, California: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, no. 27.
• Pierre Arnoul de Marneffe, Holon Programming. Univ. de Liege, Service d'Informatique (December, 1973).
• [Literate Programming]