The Literate Programming

11 Apr 2024 - João Porto

Testing the Literate Programming approach as proposed by Knuth.

TL;DR

Literate programming is an interesting approach of programming proposed by Knuth. I tested it by creating a program that is defined here. I enjoyed write code using literate programming.

Discovering Literate Programming

In the last week I was testing the Google Trends app.

To test it, I put “ Knuth” (Knuth’s name was on my mind) as the topic to be analyzed.

While checking out the results, I remembered that Knuth had proposed an approach to code called literate programming (LP).

I recalled (wrongly as we will see) that LP was an attempt to write code using natural language.

So I was curious to compare the trends of literate programming, given the recent progress of translate natural language prompts into source code powered by AI.

I found that the interest in LP is decreasing since 2008.

Then, still curious about LP, I searched about it on Wikipedia.

Reading the article on Wikipedia, I found that the idea that I had about literate programming was wrong.

Actually, literate programming is an approach where we write code as it was a book, but we still write code using a conventional programming language (PL). The key point of LP is that the code is encapsulated into a narrative that presents and explains the code for a human reader.

In contrast with the regular programming where to comment extensively the code is discouraged (for good reasons IMHO), in LP the protagonist is the explanation about the code. Then, when adopting this approach, create a program is like write a book’s narrative.

Besides propose this approach, Knuth also made a tool called WEB (in the 80s) that processes the program’s narrative and produces docs and source code. The docs can be considered the book that explain the program and the source code generated can be compiled/interpreted into a program.

In his terms, the process of generate the docs is called weaving and the process of generate source code is called tangling.

WEB originally supports TeX as the markup language to write the narrative and Pascal as the PL to be compiled. Also, WEB evolved to CWEB, that supports C and C++ as PL.

Literate Programming nowdays

So, as me, you may noticed that there are “modern” tools that provides the capability to exercise literate programming.

Indeed, Jupyter Notebook, for instance, is a clear way to create a material that mixes code and extensive explanation about it, to share the material and to turn easy the reproduction of the code and its results. A good tool for science purposes.

But, since I already used Jupyter Notebook, I was interested in check out other LP tools, specially because of the following statement in the Wikipedia’s article:

“Many of the newer ones among these [tools] don’t have macros and hence violate the order of human logic principle, which makes them more of semi-literate tools.”

The order of human logic feature is basically be able to add more code to or redefine any snippet of code previously defined throughout the narrative.

Sounds good, then I wanted to check whether this is really such a great feature or not.

The Literate tool

While reading the list of LP tools, the Literate tool drew my attention for two reasons:

It has the human logic feature (just like Knuth’s CWEB);
It supports any programming language (including my current go to language that is PHP).

Then, I have decided to try code using the Knuth’s literate programming approach and I have used Literate for that. As a result of this test, I wrote a program called Tifin and Tifin’s book is here.

How was to code using the LP approach?

Before anything, I am skeptical about the viability of to adopt literate programming in big projects with a lot of developers. I wonder whether is possible and useful to write and maintain an extensive narrative about the code in a context of CI/CD.

However, especially in a small/side project as Tifin, where the program is just an abstract idea without formal requirements, prototypes, user stories etc, I think that literate programming could be a powerful approach.

In this kind of project, is not uncommon that I get stuck trying to remember what I want/have to do when jumping from one module/class to another.

Coding with LP allows me to go back and forth in my reasoning because it is expressed in the narrative, which prevents me getting stuck trying to remember something.

Also, the literate programming is a compelling approach for those who enjoy to write prose, like me.

In general, I found that code using the literate programming approach is very enjoyable. Hence, I agree with Knuth, LP it’s a continous source of pleasure.

References

Wikipedia contributors. “Literate Programming.” Wikipedia, 3 Apr. 2024, en.wikipedia.org/wiki/Literate_programming. Accessed 10 Apr. 2024.

Wikipedia contributors. “Web (Programming System).” Wikipedia, 30 June 2023, en.wikipedia.org/wiki/Web_(programming_system)#CWEB. Accessed 10 Apr. 2024.

Knuth, Donald, and Silvio Levy. “Knuth and Levy: CWEB.” Www-Cs-Faculty.stanford.edu, 1993, www-cs-faculty.stanford.edu/~knuth/cweb.html. Accessed 11 Apr. 2024.

Wikipedia contributors. “Project Jupyter.” Wikipedia, 23 Mar. 2021, en.wikipedia.org/wiki/Project_Jupyter. Accessed 10 Apr. 2024.

Web of Stories - Life Stories of Remarkable People. “Donald Knuth - Literate Programming (66/97).” Www.youtube.com, 28 Jan. 2016, www.youtube.com/watch?v=bTkXg2LZIMQ&t=220s&ab_channel=WebofStories-LifeStoriesofRemarkablePeople. Accessed 11 Apr. 2024.

Wikipedia contributors. “Exploratory Programming.” Wikipedia, 21 Mar. 2024, en.wikipedia.org/wiki/Exploratory_programming. Accessed 11 Apr. 2024.