Lightweight literate programming

The term "literate programming" was introduced by Donald E. Knuth, who wrote several papers and a book on the subject. The central concept in literate programming is to focus on writing a document to explain the code you are writing, with that code embedded in the document in such a way that the code can be extracted to be compiled or executed.

I find this idea appealing in its own right. Besides, I think that literate programming could become a very useful practice in professional software engineering. Among other things, literate programming unifies the code with its documentation, which seems to be a better idea than trying to write and maintain separate technical documentation. The latter approach has been notoriously ineffective in the software engineering world: the documentation is often not done well in the first place, and it tends to be disregarded and become increasingly obsolete anyway as the code is maintained and modified over time.

Over the past ten years or so I have been evolving a variation, which I call "lightweight literate programming". My goal has been to simplify and streamline the technique to make it as effortless as possible to use, and make it fit so unobtrusively into the way I work that I would routinely use the technique myself! Here is a description of the idea. (This is a draft paper and is still a work in progress.)


I am accumulating a small collection of examples of lightweight literate programming in my particular style. Most of these examples are not full-sized applications, but are meant to illustrate the technique and some of the things that can be done with it.

Last modified: January 16, 2007 by Allan Stavely (email This web page is a work in progress.