[raganwald]

(Revised):

As presented in the essay, an organization of code for the purpose of explaining the code to a new programmer might differ from an organization for the purpose of maintaining the program by people familiar with its design.

The premise of the original Literate Programming was to use meta-annotations to write documentation that showed the code organized for explanations, while leaving the original in a form suitable for the machine and/or for experienced programmers.

Lacking this tool, if we use techniques like AOP to reorganize the program for explanation, we might be making things more difficult for the experienced programmer, who does not find all of the methods for a square in one place in the Square class’ definition.

[pjscott]

One approach is to structure your program in reasonably-sized modules, as usual, but to write parts of your program in a literate programming style. If a particular module is algorithmically tricky, for example, I've found that it often helps to write down very narrative-style comments, and try to organize both English narrative and code for easy reading. This helps make the code better, and for some reason seems to make difficult algorithms easier to keep track of while I'm writing them. I've written some of my best code this way.

Literate programming doesn't need to be all-or-nothing!

[hesitz]

[edit: Not sure why the downvote, since I was just trying to clarify concepts. "Literate programming" was invented and clearly defined by Don Knuth, and it muddies the water to suggest that merely doing good comments is a "literate programming style". Good commenting should be part of every programming "style", and literate programming does not primarily focus on "good commenting", focus is on two concepts described in Wikipedia article below, (1) tangling" of a primary source into machine-compilable form and (2) "weaving" of a primary source into print-formatted form suitable for human understanding.]

Merely having "English narrative" does not get you to literate programming. You can call it a "literate programming style", which is fine, but it's important to understand what true "literate programming" actually requires:

'Literate programming tools are used to obtain two representations from a literate source file: one suitable for further compilation or execution by a computer, the "tangled" code, and another for viewing as formatted documentation, which is said to be "woven" from the literate source.' http://en.wikipedia.org/wiki/Literate_programming

Tools like Javadoc are related to the second part of literate programming above, and allow for creating some formatted documentation from source code. ( http://en.wikipedia.org/wiki/Javadoc ) They don't get you all of the second part of a literate "woven" program, though, which includes text with all of the source of a program in a format suitable to be read like a book or literary essay.

Tools like Javadoc also have absolutely nothing to do with the first idea in literate programming (above), which is to have an ultimate source document where code is organized and presented in manner best suitable for human understanding, not in manner that's tailored for machine compilation (e.g., for machine-compilation the code may need to be separated into different units or files, whereas in literate source that would not be done unless it were an aid to understanding).

All that is not to say that trying to be a little more "literate" with comments in regular source code is not a good thing. But it's important to understand that "literate programming" is a clearly defined practice that requires much more than good-quality commenting.

[raganwald]

I tried to achieve this, only lacking a true LP tool, I used meta-programming to ‘retangle’ the code I’d teased apart.

[hesitz]

I think the better systems of literate programming allow you to change code in either place. I.e., you can edit the "literate code", which is "tangled" to create a directly compilable codebase. Or you can edit the "tangled" codebase, and have changes there be "untangled" to the literate form of the project.

I'm not sure whether this is an issue merely for the new versus the experienced programmer. It is an issue I see as even more important to debugging, where all the debugging tools a programmer uses are geared towards working with the compilable codebase, not the literate one. To make things work smoothly you need to be able to edit the compilable codebase and have changes be reflected in its untangled (i.e., literate) form.