The Scientific Computation System

[ Home ]   [ Screenshots ]   [ FAQ ]   [ Download ]   [ Documentation ]   [ Current State ]   [ Community ]   [ Developers ]

Why Literate Programming?

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 (July 2008) 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 9: Axiom Compiler
This is the source and explanation of the spad compiler.

• Volume 10: Axiom Algebra
This is a multi-volume set covering the algebra.

• 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.

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.

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

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