by Asim Jalis
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.
