Why Literate Programming?



Mathematics is nature's way of letting you know how sloppy your writing is. Formal mathematics is nature's way of letting you know how sloppy your mathematics is.

--Leslie Lamport Specifying Systems

Thus, it is useful to think not so much about the intrinsic interest of a mathematical result as about how effectively that result can be communicated to other mathematicians, both present and future.

--W. T. Gowers

...learning must be understood as a process of identity formation through which unknowing, unschooled novices gradually come to understand themselves as contributing, knowing members of a particular community of practice...

--Laura Agnes McNamara, May 2001

I come from a mathematics department and many mathematicians, particularly those in pure math, have a strong distrust of computers They are really not inclined to accept computer-based proofs, although there have been some dramatic examples of those in the last two or three decades.

In the early 1970s, researchers at IBM developed a symbolic algebra system called Scratchpad. This went on inside IBM for many years. There were lots of papers written about it. It ultimately got renamed to Axiom and was sold by NAG, the Numerical Algorithms Group in England, for a few years. Then it disappeared from the market and became unavailable.

People worried about this for probably about 5 years but finally NAG was able to release it. A major decision has been taken. Axiom is being completely reimplemented as a literate program. The reason is that software outlives hardware, and often its own authors. The author of Scratchpad died about 5 years ago.

So they feel the only way that this system can survive and be used by future generations is to be written as a literate program so that the reason behind the program is embedded there as part of the description of the code. I think this is really important and could be really quite significant for the future growth of computing and mathematics.

--Nelson Beebe, June 28, 2010

Language Myths. We want a language for writing reliable code.

NO! Most programmers, most of the time, scream in horror when they have to do something extra for reliability, dependability, maintainability, all the good stuff. And most programmers don't actually care. They just ship when they are told to ship. I wish we were in a field with general professionalsim but I don't see much sign of it. This is not good.

--Bjarne Stroustrup, May 2014

Writing is nature's way of letting you know how sloppy your thinking is. To think you have to write. If you're thinking without writing, you only think you're thinking.

--Leslie Lamport "Thinking for Programmers" 2014

The nature of functional programming is to build, Russian doll-style, functions that use functions that use functions etc. But without something like a literate style, your efforts are quickly lost in the details. You do stuff -- and unless you have a phenomenal memory, you've simply dug a nice, deep tunnel that is, at the same time, collapsing behind you. YOU may know what you've done, but how to make others aware and get them involved? All they see is some collapsed tunnel with a sales pitch about how you should go re-dig that very same tunnel.

--Lawrence Bottorff, February 2014

To understand a program, be the machine.
To understand text, be human.
Write for your audience.
Write Literate Programs.

--Tim Daly April, 2013

In my life as an artchitect, I find that the single thing which inhibits young professionals, new students most severely, is their acceptance of standards that are too low. If I ask a student whether her design is as good as Chartres, she often smiles tolerantly at me as if to say, "Of course not, that isn't what I am trying to do...I could never do that."

Then, I express my disagreement, and tell her: "That standard must be our standard. If you are going to be a builder, no other standard is worthwhile."

--Christopher Alexander, May 1996 in (Patterns of Software, Gabriel)

The best programming language is English. Everything else is notation.
-- Tim Daly (2011)

Here is an example literate program in HTML
Here is a Journal article about Literate Programming and Reproducible Research

I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title "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, p99

Step away from the machine.
Literate programming has nothing to do with tools or style.
It has very little to do with programming.
One of the hard transitions to literate programming is "literate thinking".

-- Timothy Daly (2010) in Lambda the Ultimate forum [LTW10]

The hardest part of literate programming is the documentation.

--Timothy Daly (2011)

The effect of this simple shift of emphasis can be so profound as to change one's whole approach to programming. Under the literate programming paradigm, the central activity of programming becomes that of conveying meaning to other intelligent beings rather than merely convincing the computer to behave in a particular way. It is the difference between performing and exposing a magic trick.

--Ross Williams, FunnelWeb Tutorial Manual, pg 4.

Another thing I've been enjoying lately is literate programming. Amazingly it turns out to be faster to write a literate program than an ordinary program because debugging takes almost no time.

--Bill Hart, SAGE Mailing list, May 3, 2010

The conversation is much more direct if the Design Concept per se, rather than derivative representatives or partial details, is the focus.

--Fred Brooks: The Design of Design: Essays from a Computer Scientist.

We are banning the old notion of literate programming that I used when developing TeX82 because documentation has proven to be too much of a pain.

--Donald Knuth TUG 2010

And on Axiom's "30 Year Horizon" focus:

The index to Digital Typography lists eleven pages where the importance of stability is stressed, and I urge all maintainers of Tex and Metafont to read them again every few years. Any object of nontrivial complexity is non-optimum, in the sense that it can be improved in some way (while still remaining non-optimum); therefore there's always a reason to change anything that isn't trivial. But one of Tex's principal advantages is the fact that it does not change -- except for serious flaws whose correction is unlikely to affect more than a very tiny number of archival documents.

-- Knuth, Donald The Tex tuneup of 2014

Once upon a time I took great care to ensure that TeX82 would be truly archival so that results obtainable today would produce the same output 50 years from now but that was manifestly foolish. Let's face it, who is going to care one whit for what I do today after even 5 years have elapsed, let alone 50. Life is too short to re-read anything anymore in the internet age. Nothing over 30 months old is trustworthy or interesting.

--Donald Knuth TUG 2010

From a November, 2011 Knuth interview:

Yet to me, literate programming is certainly the most important thing that came out of the TeX project. Not only has it enabled me to write and maintain programs faster and more reliably than ever before, and been one of my greatest sources of joy since the 1980s -- it has actually been indispensable at times. Some of my major programs, such as the MMIX meta-simulator, could not have been written with any other methodology that I've ever heard of. The complexity was simply too daunting for my limited brain to handle; without literate programming, the whole enterprise would have flopped miserably.

If people discover nice ways to use the newfangled multithreaded machines, I would expect the discovery to come from people who routinely use literate programming. Literate programming is what you need to rise above the ordinary level of achievement. But I don't believe in forcing ideas on anybody.

-- Knuth, Donald Interview with Donald Knuth

An abbot of the Seven-Clawed Blind Eagle Clan was tallying the deliverables of the temple monks, when he noticed that a monk of the Laughing Monkey Clan had produced no design documents.

"What if a problem were discovered in our production system?" the abbot asked the monk. "How would the cause be understood by any besides yourself?"

"The code itself should be examined," said the monk. "The Document is a sickly beast, easily subject to the Three Plagues of Error: omission, obfuscation, and obsolescence."

The abbot reported this to the Java master, who said: "Have the monk balance on one foot with his staff outstretched, every day from dusk to midnight. If he can say a word to please me I will revoke the punishment, but not otherwise."

"Is there such a word?" asked the abbot.

"It is difficult to be certain," reflected the master. "Yesterday I was pleased by the sound of a cricket chirping after the first three drops of rain. The day before, the plashing of milk in a pail returned me to a pleasant memory of my youth. Perhaps the answer lies in the fragrance of a white lotus that drifted once in a pond below my window."

--Qi The Codeless Code

Then anyone who leaves behind him a written manual, and likewise anyone who takes it over from him, on the supposition that such writing will provide something reliable and permanent, must be exceedingly simple-minded; he must really be ignorant of Ammon's utterance, if he imagines that written words can do anything more than remind one who knows that which the writing is concerned with.

-- Socrates

All I need in the documenation is to be reminded of that which the writing is concerned with.

-- Tim Daly


Once a program has been developed and the developers have moved on to other tasks it needs to be maintained. The fundamental problem is that if you modify code you didn't write, you don't see the big picture and you don't understand the reasons why the code is written the way it is. Thus changing code without a larger context is almost always going to introduce new bugs.

The only way to correctly change code is to deeply understand the implications of the change. This requires a deep understanding of the code and an awareness of the big picture. Yet the "why" of code is rarely ever written down in standard programming practice. The goal is only to elaborate the "how" so the machine can perform the task. The programmer communicates with the machine.

Literate programming, as used in Axiom, is an attempt to communicate with other users, developers, and researchers in addition to the machine. The goal is to have the program read like a story so that others can understand the rational, the theory, the choices, the implications, and the implementation context as well as the "how".

This code is intended to live forever but it is highly probable that you will not. Write to communicate with the next person to pick up the torch. When you explore code, write down what you learn. When you change code, explain why you made your choices. When you write new code explain what others need to know to maintain it.



User documentation


The Axiom system is gradually being documented in a set of volumes. These change with every update to the system since they contain the actual system source code. The volumes listed here are updated every other month when the system is distributed. The current volume set is:

Axiom is being reworked to use the Firefox browser as the new front end. Static pages from the new hyperdoc show some of the details. These pages will be "live" in the new Axiom hyperdoc.

The Axiom build graph shows the algebra hierarchy in required build order. Note that the edges in the graph only show dependence on the prior level in the hierarchy. There are approximate 1100 total nodes. Each node represents a single domain, category, or package. Graph nodes that are elliptical show objects that get build as part of the bootstrap process.

The algebra graph in its current form is available. You'll need a reasonably new browser to see the graph. This is a work in progress.

The Rosetta (src) (pdf) document is a comparison of nearly equivalent commands between many different computer algebra systems.

This is the announcement for the Axiom Conference at City College of New York in April, 2005