Is literate programming dead?

Question

A fair bit is written about literate programming, but I've yet to see any project that uses it in any capacity, nor have I seen it used to teach programming. My sample may small, so I'm looking for evidence that literate programming exists and is successful in the real world.

Answer 1

I'm not sure it was ever alive. I certainly found Knuth's articles on the subject less than convincing, particularly the use of TeX for the markup language. Actually I think the use of any markup language would probably doom it - the technique cries out for a really powerful IDE, and as far as I know, none ever materialized.

Answer 2

First, javadoc is a kind of Literate Programming. You are creating documentation and code from a single source. It isn't very good, but it's certainly a form of LP.

Traditional Web/Weave Literate Programming creates documentation and code from a original source files using a specialized markup language. The final document can be elegant and easy-to-work with. The code is the code; but the presentation can focus on important elements, leaving the annoying language-specific machinery for an appendix.

But creating documentation from code is also a form of Literate Programming. The point is to create nice documentation and code from a single source. Java API doc's aren't brilliant, but they're pretty darn good. And including the package overview HTML file is a huge step toward LP from the Java source.

I'd argue that Doxygen, JavaDoc, Epydoc, Sphinx, etc. are a kind of Literate Programming.

Doesn't look dead from the following evidence.

Consider this:

http://en.literateprograms.org/LiteratePrograms:Welcome

http://www-cs-faculty.stanford.edu/~knuth/programs.html

Also consider this IDE for Literate Programming:

http://webpages.charter.net/edreamleo/design.html

Also, consider the original tool suite:

http://www.literateprogramming.com/cweb_download.html

While it hasn't been updated in 2010, it's pretty stable, and doesn't need many updates. It's still being downloaded and used.

Dead is too strong.

Literate Programming is difficult. Jon Bentley's observation: "a small percentage of the world's population is good at programming, and a small percentage is good at writing; apparently [Knuth is] asking everybody to be in both subsets."

Some folks try it and leave because there's one aspect that's particularly hard: debugging. The two-step jump from original source document to program code to traceback output from an error in a unit test is difficult to work with. The line numbers are source code line numbers not original documentation line numbers, and that's a bother.

Answer 3

Literate Programming was a big deal back in the 80's and 90's. Like all programming process fads, it had its day until some other great new thing (extreme programming) came along.

Someday a new fad will come along, and people will be on SO asking "whatever happened to extreme programming?"

Of course, like most of the better passed fads, it did leave some traces. Auto documenters like doxygen are a direct result of all the thought put into Literate Programming.

Answer 4

The problem with the whole idea is that you have to be a good programmer and a good writer; Knuth may be one of the few people who can do both well.

From a "real world" point of view, there is a heavy dose of YAGNI. Why spend all this time extensively documenting something that might not be around in six months? Knuth's programs have lived for decades, so the investment was worth it for him.

Answer 5

With the size of the R community around here I surprised no one has mentioned Sweave yet. This is similar approach, buts seems to take the the approach

Embed the program in the document.

and opposed to Knuth's drive to

Embed the documentation in the program.

In either case, however you write a combined source which is processed to give both document and calculation.

Likewise LaTeX classes and packages can be (and usually are) written with the documentation in a unified file. In the case of something like the memoir class this can print out as considerable pile of dead trees: well nigh a book.

Finally, while today's automatic documentation generators don't have quite the sweeping scope of Knuth's vision I see them as being in the same category.

Answer 6

I saw Knuth's articles on it, and very little else.

I was intrigued by it until I found out what I'd have to write in order to create a literate program: I'd have to write the program and design the documentation in one file, with odd commands. It looked like too much work for most programs, particularly in more experimental programming, where I'd want to try several different things, and where it would represent premature optimization of the documentation. Moreover, I didn't find Knuth's example all that easy to read.

It occurred to me later that this wasn't the only problem. We know what the big problem is in having separate program and documentation files: the documentation, however well done, gets out of date. However, we also know what happens when the documentation is in the form of comments: it gets out of date, although typically not quite as fast. As a result, lots of us try to write generally readable code, and are very good at reading the code. Literate programming seemed to me to break up the usual methods of reading the code, so having people keep the text pieces up to date was vital for understanding the program.

This is more an explanation of why literate programming is dead, but it seems at least mostly dead, in that it's been years since I saw anything about it. It did have an effect, in that it pushed for more structured ways to document in the code and ways to extract meaning from code.

Answer 7

Only used by people who wrote their own LP systems

Chris Van Wyk of Bell Labs had a series of articles on Literate Programming back in the late 80's. He wrapped up the series with the article referenced below (subscription-only link) with the conclusion that the only people who were using Literate Programming were people who had written their own Literate Programming systems.

http://portal.acm.org/citation.cfm?id=316051&dl=GUIDE&coll=GUIDE&CFID=82297188&CFTOKEN=42986299