First off, I would like to begin by saying that this post will be a little different than usual. It is not so much an explanation, a tutorial, or the asserting of an opinion (and you all know what an unopinionated fellow I am), as it is a monologue like discussion. Running through possibilities, tossing out ideas, but it is not likely to present any firm conclusions. So, here we go.
I recently read Donald Knuth’s paper on WEB, a literate programming system that he wrote with others for their own use. The paper is listed in the references section. At first glance, literate programming makes perfect sense in academia. Code is not written that is not intended to be published as either a paper or a book. Using literate programming makes the task of doing both easier. As the content of the code changes, the commentary itself is readily changed to match.
The question that comes to mind, though, is whether or not literate programming has potential for the working programmer. In Academia, the real work is generally not the programming. The programming itself is merely a way to try to prove whatever the hypothesis is. It is the equivalent to a test in a physics laboratory. The working programmer is not using his code as a mere test. It is the final product and it has to work. Moreover, it must also be delivered in a reasonable (or, more often, unreasonable) amount of time. In this different atmosphere, does literate programming still have a place? Would it work as well for someone writing code to track truckloads as it does for Knuth when he writes his books? At first glance, it would be easy to say no, but Knuth extols the methodology for reasons that most programmers would find appealing. He intimates the LP makes maintenance easier.
If there is anything the working code monkey would love to see, it is an easier job in maintenance. Most of us have had that experience of looking at a screenful of code and wondering what he (or I) was thinking when this was written. If we are writing down are reasoning with the code, then the questions go away. We may not agree with the reasoning, but at least we would understand the angle from which the problem was hit. Naturally, most people would do as poor a job of maintaining an essay as they would the comments (there are virtually no comments in my production code). As with any methodology, its utility stands on its practitioners, not on its non-practitioners.
On StackOverflow, several users run down the idea as being outdated or outmoded, being suited to the dark days of when we were limited to two-character variable names. While the utility may be increased under such conditions, they have missed the point. Literate programming is not about writing a lot of comments–it is about writing a book or article on the problem, side by side with the problem’s solution. Literate programming is not an idea confined to a specific time. It is not a hack (as intimated). It is a way of looking at programming that turns the whole process on its head. The machine becomes auxiliary, the human audience becomes primary. It may be that this approach does not hold practical utility–but it is not something to be as lightly shoved aside as the idea of starting a completely new and independent piece of software in RPG III.
These rambling thoughts led me to look into some present day tools (even Knuth’s own WEB has been superseded, it seems). The one with the biggest following is noweb, which is language agnostic. My biggest complaint as I fish through the tools I could find, is that they were almost universally using TeX as their typesetting format. Historically speaking, this makes sense. Knuth wrote WEB and TeX and, more specifically, he wrote WEB for TeX. I, however, do not want to compose text in TeX or LaTeX. As I have written before, it is just to cluttering. There are a few out there that rely on something else. I found one that used wiki syntax. At least noweb supports HTML mode which, while still imperfect for composition (as an interchange and basic display format, it is excellent), is at least usable.
Any value that LP has will largely rest on the fact that it forces the programmer to think a little bit more about what he is doing as he is doing it. In this way, it is not unlike Haskell’s type system (which also makes it unsurprising that the Haskell community is one of the more vibrant outposts for LP).
A lot of questions still remain. Most LP tools are usable for standard write-compile-test cycles. For languages like Lisp, a separate tool would have to be created (not that a lot of weekend warrior projects do not already exist). On StackOverflow, a few users expressed concern for how you would use LP in a collaborative environment. Personally, I would suspect that it would work similar to the way that most technical writing team works: divide and conquer. Distributed source control systems like git or darcs make this even easier.
So what is it then? Academian pipe dream or underused tool? There is only one way to find out. Try it.
References
