Literate Programming

There are at least two compelling reasons for taking the trouble to learn and use one or more literate programming packages. Both involve the development and maintenance of large sets of code. The first is the desire to create new, large software projects that will be used, in both the near- and far-term, by a defined user community; and in the far-term, will experience subsequent maintenance and further development by other coders. Second the inheritance of large legacy code packages by a developer/maintainer with the assignment to:

	learn the code (well enough to...)
	document it in detail, and
	develop it further.

The literate programming paradigm, as created by Donald Knuth, is the availability and use of software tools that allow the programmer to build up large amounts of code, a piece at a time, and in stream-of-consciousness order.

For example, suppose an engineer is developing a robot arm for use in manufacturing. He or she would, in no really predictable order, write code to describe a jointed arm as a distributed mass system, assign masses, and moment and products of inertia to each of the components, describe the linkages in terms of how they can move and how they cannot. Pretty soon the engineer realizes that a common reference frame is needed, so describing this reference frame is added. Then it is realized that reference frames fixed with respect to individual segments of the mechanical assembly are naturally assumed in their description, so more code is written to allow descriptions of position and velocity in terms of the one meta-reference frame, as needed. Suddenly, a new requirement arrives which stipulates a certain function for the finished assembly. More code is needed. And then more. The power of literate programming is ability to write code, one piece at a time, and in the order most natural to the programmer.
Here is another scenario. Suppose an engineer were to be given a large software package that was written years and ago and has been added to and ported between various computer platforms since that time. Documentation was written, but "by committee," and it hasn't been maintained carefully since the software was first released. In spite of that, the code is important, is still being used, and it needs to be maintained and documented.

The engineer could dump the entire packages into a "web" file and he or she could then go to work, learning it piece-by-piece, over time, and gradually developing an understanding of what the capabilities of the software are, and what needs to be added, cut, and/or modified. All the power of LaTeX can be used. (LaTeX is the dominant typesetting software for documentation of technical material, which can be heavy with math equations, cross-referencing, and bibliographical citations kept in a database. )

Note that the introduction of literate programming practices is more than just adding copious comment lines to the input files. These comments can be substantial documentation of both the chunks of code and how they fit together. In addition, diagrams of whatever complexity is needed can be put directly in the code, further documentation what is intended and further grounding the code firmly in theory and in the understanding of the engineer programmer.