[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.