Introduction to Literate Programming

I’ve found the best uses for literate programming (LP) are for languages that are:

• Succinct (notice I didn’t say cryptic)
  
• New (not every team member knows everything), and
  
• References or includes other languages (like SQL)
  

However, any sufficiently complicated problem or exploration could benefit from an LP approach.

I have found that to correctly do literate programming, you need the following:

• A good editor that can deal with code
  
• A good editor that can deal with prose
  
• A tool to identify and separate the source code blocks
  
• A tool to connect (include) one code blocks in another code block
  
• A way to tangle the source code out to more than one file ( Note: this allows you to keep your code and tests together)
  
• A way to evaluate source code blocks
  
• A process to create a literate programming document for others to read
  

Consequently, I have found that using Emacs, with org-mode and its Babel project is nearly ideal.

What does it look like to work this way?

Here are a few screen-shots of my Emacs environment showing an example of working through the Coin Change Kata in Clojure (but including a snippet of the solution in Scala):

Notice how the source code can have embedded hyperlinks to background or notes:

Code blocks can be executed/evaluated directly in the file, and the results can be re-inserted as “text” back into the file, which can then be assigned as a data variable for another code block…which may be code in a different language from the first.

Snaking data through code in this way is for illustrative purposes, which is different than the code written to the final source code files. ^{}

Another nice feature of org-mode is dividing your program into actual sections that can be collapsed:

Some code blocks can contain Graphviz or PlantUML instructions, which can serve to illustrate the code, and the diagrams can be embedded in the produced documentation:

In the example below, I begin with a literate program formatted using org-mode, and then render the code file, as well as export a readable verison to HTML:

Many people have talked about the Coin Change Kata, as a way to practice our coding craft. I thought it would be fun to try it in a literate way, and this is the results. I suggest viewing the tangled web page first.

coin-kata.org

↓

↓

coin-kata.html

   

coin-kata.clj coin-kata-tests.clj

In this example, my literate file included both the solution code as well as the tests (having them side-by-side like can be informative). The tangling process separated it into two separate source code files.

Should all programs be written in such a style?

A couple years after Knuth officially published his literate programming ideas, he published an example in Jon Bentley’s “Programming Pearls” column [Communications of the ACM 29, 5 (May 1986), 364-3691]. Doug McIlroy added a rebuttal where he boiled Knuth’s example into a single (now famous) shell command:

    tr -cs A-Za-z  '\n' |
    tr A-Z a-z |
    sort |
    uniq -c |
    sort -rn |
    sed $ { 1 }q

McIlroy invented the shell pipe as well as many of those command line tools. He’s quoted as saying:

A wise engineering solution would produce—or better, exploit—reusable parts.

His example proved his point. However, given a complex problem without the necessary components, perhaps composing your initial solution in a literate program is helpful?

Further reading:

• Introduction to org-mode’s Babel Project for teaching Emacs to do Literate Programming
  
• Reference material for the Babel Project
  
• More Shell, Less Egg is a good historical essay on this subject
  
• Where have all the Literate Programmers gone?
  

^{}

If you understood this paragraph, you would have achieved a sort of literate programming satori, however, I doubt that my prose sufficiently explains this concept.

Check out my essay on Literate Devops for better examples.

Date: 2013 Jan 15

Created: 2020-12-23 Wed 10:14