[Axiom-developer] Literate programming

[daly]

I see that my Literate Programming session is beginning to gain some
traction. I would encourage you to bring examples. We can discuss the
merits and possibly gain some new insights. If nothing else, please
sign up for the Literate Software session at Clojure-Conj. I promise
to keep it short.

Literate programming can take various forms. I am working on a survey
of literate software. I came across an interesting non-latex example
worth sharing:

http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html

Notice how well they have documented an apparently simple line as in:

  exports.Base = class Base

  The Base is an abstract base class for all nodes in the syntax tree.
  Each subclass implements the compileNode method, which performs the
  code generation for that node. To compile a node to JavaScript, call
  compile on it, which wraps compileNode in some generic extra smarts,
  to know when the generated code needs to be wrapping up in a
  closure. An options hash is passed and cloned throughout, containing
  information about the environment from higher in the tree (such as
  if a returned value is being requested by the surrounding function),
  information about the current scope, and indentation level.

Notice how this is not only giving trivial information (e.g. Base is
an abstract base class) but WHY it exists (..as a base for all nodes in
the syntax tree). It gives operational information (to compile a node..)
as well as information about the effect (..which wraps...). It shows
how global information is used (An options hash..) and WHY (containing
information about the environment...)

Code only tells you HOW something is done at the time it is done.
It's like having a recipe without an idea what you would make.

If our standards of documentation were raised to this level then large
systems like Axiom, Clojure, and ClojureScript would be much easier to
maintain and modify in the long term.

If you want your code to live beyond you, make it literate.

Tim Daly
address@hidden