Literate Programming

Ever since Donald Knuth published “Literate Programming” back in 1984, I’ve been a fan. Telling a computer how to run a program and helping a human understand it are two different but very necessary things.

Of course all programming languages have a commenting facility. But often that is just not sufficient to explain what is going on in a program. In my own work, the typical commenting facilities simply do not how the power to describe algorithmic details efficiently, particularly in the area of mathematics. Knuth addressed the problem with his WEB, and later, CWEB programs. He invented the TeX typesetting system and LaTex document preparation system in pursuit of this goal. His efforts have been embraced by the scientific community, particularly in the area of mathematics.

Others have been inspired to take up the cause as well. For example, the FWEB system provides literate programming tools for FORTRAN. The Racket project has created a very powerful new tool to create documents for their Scheme-like group of languages. The Scribble tool provides a very comfortable tool for creating documentation and doing literate programming in the Racket environment. The article “Scribble: Closing the Book on Ad Hoc Documentation Tools” describes this system briefly. As you might expect, detailed documentation exists elsewhere and is update regularly.

Another recent tool is Marginalia for Clojure created by Michael Fogus. Graphically, this tool takes a different approach. As the name suggests, it presents the program and commentary as two columns, sort of like you might annotate a book in the margins. I haven’t used it seriously yet and it may not support the description of complex math (or maybe it does), but it is certainly a pleasure to read the output.

There doesn’t seem to be a canonical system or tool for literate programming in Lisp, although there are a few examples with noweb. This site seems to promise a new “system real soon now”. The report on the system looks promising.

However, of all the systems out there, the real champion for literate programming is Mathematica®. Mathematica is a computer mathematics systems at its heart. You can do extensive and sophisticated symbolic mathematics as well as create numerical results. Programming is done using a language that has some very Lisp-like characteristics. But the thing that makes it so useful for literate programming is the notebook interface. You can do everything you want in the notebook: write text with mathematics, do symbolic math, do numerical math, program, plot results and so on. The notebooks are “live”, so you can make changes and recalculate at any time. You can send the notebooks to others with a Mathematica system so they can change arguments, fiddle with settings, and experiment as they see fit. The notebooks can be converted to high quality PDF files for those who don’t have Mathematica, although they won’t be able to do the same manipulations.

My favorite use of Mathematica is working through new algorithms that appear in the literature. I can create what I call “walkthroughs” of the paper describing the math, noting my interpretation, creating functions that implement the algorithms, plotting results, and so on. When completed, these can be shared with colleagues to help their understanding or to check my assumptions and interpretations. For example, I once worked through an unsupervised color deconvolution method for a project I was working on. It turned out that the algorithm did not work robustly for what we needed. However, a colleague at another site of my company was trying to get the same algorithm to work for a different purpose, but having difficulty with the implementation. A third colleague knew of my previous work and sent them a copy of the notebook. It produced the desired “Aha!” moment and someone got some use of my work.

Mathematica has been around for a long time and is constantly improving. It’s a great thing.