Why Literate Programming?
--Leslie Lamport Specifying Systems
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.
--W. T. Gowers
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.
--Laura Agnes McNamara, May 2001
...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...
--Nelson Beebe, June 28, 2010
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.
--Bjarne Stroustrup, May 2014
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.
--Leslie Lamport "Thinking for Programmers" 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.
--Lawrence Bottorff, February 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.
--Tim Daly April, 2013
To understand a program, be the machine.
To understand text, be human.
Write for your audience.
Write Literate Programs.
--Christopher Alexander, May 1996 in (Patterns of Software, Gabriel)
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."
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
-- Donald Knuth "Literate Programming (1984)" in Literate Programming CSLI, p99
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.
-- Timothy Daly (2010) in Lambda the Ultimate forum [LTW10]
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 (2011)
The hardest part of literate programming is the documentation.
--Ross Williams, FunnelWeb Tutorial Manual, pg 4.
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.
--Bill Hart, SAGE Mailing list, May 3, 2010
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.
--Fred Brooks: The Design of Design: Essays from a Computer Scientist.
The conversation is much more direct if the Design Concept per se, rather than derivative representatives or partial details, is the focus.
--Donald Knuth TUG 2010
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.
And on Axiom's "30 Year Horizon" focus:
-- Knuth, Donald The Tex tuneup of 2014
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.
--Donald Knuth TUG 2010
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.
From a November, 2011 Knuth interview:
-- Knuth, Donald Interview with Donald Knuth
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.
--Qi The Codeless Code
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."
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.
-- Greg Wilson "What We Actually Know About Software Development" https://vimeo.com/9270320
Listening to computer scientists argue, it seems that the standards of proof is "I've had two beers and there is this anecdote about a tribe in New Guinea from one of Scott Birkins books that seems to be applicable."
The debate is hindered by low standards of proof.
-- Tim Daly
All I need in the documenation is to be reminded of that which the writing is concerned with.
TXV - posted on Hacker News
What do you do with undocumented legacy code? I have A LOT of this to deal with right now. There are whole libraries used across multiple webapps and services that are completely undocumented. No javadocs, no comments in the source code, no flow diagrams, no written explanations, nothing. Some of these libraries don't even have source code attached to them, and of course there are no information about them whatsoever on the internet, so they must have been developed internally, or even worse, borrowed from mysterious sources. Needless to say that the original devs are long disappeared, even before I joined the team.
posted on Hacker News
Donald Knuth, like a genius, shattered my illusions. He is so confident in his code, that he pays bug bounties from his own pocket; for any kind of bug. Knuth doesn't write code in small pieces. He goes six months or so without testing his code, then he tests it all at once. When he tests, he says, "I get into the meanest, nastiest frame of mind that I can manage, and I write the cruelest test code I can think of; then I turn around and embed that in even nastier constructions that are almost obscene." At that point, he tries to test everything. Still, the question is raised, how does Knuth keep things straight without testing for so long?
Knuth invented literate programming to keep his thoughts clear. He intertwines the documentation with the code, like a story. Literate programming lets him structure the code in a way that is easiest to read. He says, "The extra time I spend in preparing additional commentary is regained because the debugging time is reduced."
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.
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:
- Combined Table of Contents This is the table of contents from the existing volumes combined into one document for easy reference.
- Volume 0: Axiom Jenks and Sutor This is the reconstructed Jenks and Sutor volume.
- Volume 1: Axiom Tutorial This is the tutorial volume ISBN 1-411-66587-X. Hardcopy is available from Amazon.com or Lulu.com
- Volume 2: Axiom Users Guide This is a more detailed explanation with current information for Axiom users.
- Volume 3: Axiom Programmers Guide This is information about the language and algebra hierarchy for Spad language programmers.
- Volume 4: Axiom Developers Guide This is a collection of useful information for developers.
- Volume 5: Axiom Interpreter This is the source code and explanation for the interpreter.
- Volume 6: Axiom Command This covers the axiom commands, sman, and some other system related issues.
- Volume 7: Axiom Hyperdoc This is the source and explanation of the X11 hyperdoc subsystem.
- Volume 7.1: Axiom Hyperdoc Pages This is the source and pages for Hyperdoc.
- Volume 8: Axiom Graphics This is the source and explanation of the X11 graphics subsystem.
- Volume 8.1: Axiom Gallery A gallery of Axiom images.
- Volume 9: Axiom Compiler This is the source and explanation of the spad compiler.
- Volume 10: Axiom Algebra Implementation This is a multi-volume set covering the algebra. The first volume deals with implementation issues.
- Volume 10.1: Axiom Algebra Theory This volume gives background theory for various algebra topics.
- Volume 10.2: Axiom Algebra Categories This is the source code for all of the categories.
- Volume 10.3: Axiom Algebra Domains This is the source code for all of the domains.
- Volume 10.4: Axiom Algebra Packages This is the source code for all of the packages.
- Volume 10.5: Axiom Algebra Numerics This is the source code for all of the numerics.
- Volume 11: Axiom Browser This is the source and explanation of the new Firefox browser front end.
- Volume 12: Axiom Crystal This is the design documents and internals for the crystal interface.
- Volume 13: Proving Axiom Correct This is the work on proving Axiom correct.
- Axiom Bibliography This contains all the literature references to, and from, Axiom.
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.
This is the announcement for the Axiom Conference at City College of New York in April, 2005