Why Literate Programming?



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

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.



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.

A first tutorial is available at: http://www.dcs.st-and.ac.uk/~mnd/documentation/axiom_tutorial/

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