Donald Knuth's WEB
"Programming is best regarded as the process of creating works of literature, which are meant to be read.
Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other."
[Donald Knuth, "Literate Programming (1984)" in Literate Programming. CSLI, 1992]
"My shtick is to promote the idea that humans, not computers, read programs."
"I ask programmers to think of themselves as writers, teachers, expositors. When you're programming, the very act of trying to explain it to another human being forces you to get more clarity. And then later on, you can maintain, modify, and port your programs to other platforms much more easily. Even if your only audience is yourself, everything gets better."
"Computer programs are the most complicated things that humans have ever created. That's why I say this idea of exposition is the best way of coping with the complexity. When I'm writing a program, I approach it as if I were writing a short story. It doesn't take me longer, because the time I spend on organization is more than made up for in time saved debugging."
This sample calculation of the first 1000 prime numbers gives a taste of Knuth's method. See pages 6 and 7 for the amount of markup used to prepare the WEB text for WEAVE and TANGLE.http://www.literateprogramming.com/knuthweb.pdf