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.

— Donald Knuth. “Literate Programming (1984)” in Literate Programming. CSLI, 1992, pg. 99.

Literate Programming is hardly a new idea and it was never popular enough that Wired or TechChrunch would have pronounced it dead at any given time. Recently however, a few tools appeared that implement some of the ideas from LP.

The first of these is Docco which generates HTML that shows the documentation alongside the code. The input is the commented source code, so that no tools are needed to convert it to be used as a program. With Knuth’s original LP, you wrote in a special kind of language – mixing your programming language with Latex – from which the source code could be extracted.

Inspired by Docco, Michael Fogus wrote Marginalia to work with Clojure code, extracting the text from both comments and function documentation.

These tools, however, do not have all the features to be considered literate programming in the original sense. Most notably missing is the ability to organize the source strictly by the flow of the text and not by the needs of the compiler to have stuff declared before they are used.

I tried out Marginalia and the literate-programming-lite-style for my clj-bookmarks library (it’s a client implementation for the Delicious and Pinboard APIs). The result is here and the code is on GitHub.

Although there are some minor bugs in Marginalia, I am mostly happy with the result. I might continue this experiment.