Literate programming

Literate programming is a philosophy of computer programming based on the premise that a computer program should be written similar to literature, with human readability as a primary goal. According to this philosophy, programmers should aim for a “literate” style in their programming just as writers aim for an intelligible and articulate style in their writing. This philosophy contrasts with the mainstream view that the programmer’s primary or sole objective is to create source code and that documentation should only be a secondary objective.

In practice, literate programming is achieved by combining human-readable documentation and machine-readable source code into a single source file, in order to maintain close correspondence between documentation and source code. The order and structure of this source file are specifically designed to aid human comprehension: code and documentation together are organized in logical and/or hierarchical order (typically according to a scheme that accommodates detailed explanations and commentary as necessary). At the same time, the structure and format of the source files accommodate external utilities that generate program documentation and/or extract the machine-readable code from the same source file(s) ("e. g.", for subsequent processing by compilers or interpreters). The relevance of literate programming has been reduced a bit by features such as syntax highlighting in later programming environments.

History and current implementations

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 "TeX: The program", volume B of his 5-volume "Computers and Typesetting". Knuth had privately used a literate programming system called DOC as early as 1979; he was inspired by the ideas [Pierre Arnoul de Marneffe, "Holon Programming". Univ. de Liege, Service d'Informatique (December, 1973).] of Pierre Arnoul de Marneffe. The free CWEB, written by Knuth and Silvio Levy, is WEB adapted for C and C++, runs on most operating systems and can produce TeX and PDF documentation. Other implementations of the concept are noweb and FunnelWeb, both of which are independent of the programming language of the source code.

The Leo text editor supports optional noweb and CWEB markup. [ [http://webpages.charter.net/edreamleo/front.html Leo homepage cites support for noweb and CWEB] ]

The Haskell programming language has native support for literate programming, inspired by CWEB but with a simpler implementation. When aiming for TeX output, one writes a plain LaTeX file where source code is marked by a given surrounding environment; LaTeX can be set up to handle that environment, while the Haskell compiler looks for the right markers to identify Haskell statements to compile, removing the TeX documentation as if they were comments. Haskell's functional, modular nature [ [http://www.cs.chalmers.se/~rjmh/Papers/whyfp.html Why Functional Programming Matters] ] makes literate programming directly in the language sensible, making a separate code generation pass unnecessary (compare WEB's TANGLE pass that generates imperative Pascal code). This is made possible by Haskell's declarative, purely functional, lazy semantics: arbitrary sections of code can be factored into separate functions and documented as separate conceptual units, without changing the semantics of the compiled program.

Perl also supports literate programming using Plain Old Documentation or POD to combine human readable documentation and basic formatting with source code. This embedded documentation is also commonly parsed from the code into other formats, including HTML or LaTeX.

ee also

* Intentional programming
* Leo (text editor)

References

Further reading

*Donald E. Knuth, "Literate Programming", Stanford, California: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, no. 27.
*Eitan M. Guari, "TeX & LaTeX: Drawing and Literate Programming". McGraw Hill 1994. ISBN 0-07-911616-7 (includes software).
*Kurt Nørmark, " [http://www.cs.aau.dk/~normark/litpro/issues-and-problems.html Literate Programming - Issues and Problems] "

External links

* [http://www.faqs.org/faqs/literate-programming-faq/index.html comp.programming.literate FAQ] at internet FAQ archives
* [http://groups.google.com/group/comp.programming.literate Literate Programming newsgroup]
* [http://www.literateprogramming.com/ Literate Programming website]
* [http://en.literateprograms.org/ LiteratePrograms] is a literate programming wiki.
* [http://moonflare.com/code/select/index.php Select: A literate programming example] using noweb
* [http://www.softpanorama.org/SE/literate_programming.shtml Softpanorama page on literate programming]
* [http://www.haskell.org/haskellwiki/Literate_programming Haskell literate programming] , [http://www.haskell.org/onlinereport/literate.html Specification of literate programming in the Haskell Report, the accepted Haskell standard]