I recently read Don Knuth's "Literate Programming". It seems to me that a lot of writing on the web ignores the main point of literate programming. The main point is not to mix comments and code. That is pretty easy to do in most languages.

What Don is really talking about is how to lay out your program so that it's layout matches the way we think rather than the way a compiler works.

When I write a program (when I am not using XP and when I am not pairing) I spend some time writing notes to myself, reflecting on the program, and exploring what different parts of it will do.  The final product is still vague. I am just getting a feel for the conceptual space around the program. I am also trying to poke around my understanding of the problem I am trying to solve. My notes consist of a lot of English, some of it transformed into pseudo-code, and some of this translated into actual code. It also contains data definitions.

Eventually when I have a reasonable grip on what needs to be done I start coding. At this point I throw away all my notes.

Don is proposing a system in which I can run my notes through a pre-compiler (which he calls WEB) to produce my program. This way the notes stay connected to the code.

In these notes the flow of reasoning is neither top-down nor bottom-up. In fact it bounces around between components -- like a web. Each time I pin down a detail on one side I have to come back and talk about how this will impact other decisions in other components. So its a winding iterative process.

Compilers do not permit this kind of flimsiness. The require that you talk about one thing at a time. They cannot talk about something else for a while and then come back to the original point. Compilers can only follow one train of thought at a time.  They have tunnel vision. They are incapable of taking a global view of the system. They are focused on getting the job done and if you leave out the smallest detail or try to change the subject midstream in the conversation they completely freak out.

The ability to add comments does not change this basic fact about how compilers expect code to be laid out. You are only allowed to talk about one thing at a time. And once you start talking about a class you cannot change the subject till you have said everything there is to be said about the class.

In my mind Literate Programming is a way to get around this incompatibility in thinking. I don't know how well Don's system does this job. But whether he succeeds or not, it seems like a worthwhile goal to make the layout of computer code more compatible with the way we (humans) think, explain things to each other and understand new things.