Write programs as if they were mathematical essays, but with code instead of equations. This is “literate programming”, an idea invented by the famous computer scientist Donald Knuth. The quote below is from www.literateprogramming.com , apparently first published by Knuth in “Literate Programming (1984)” in Literate Programming, CSLI, 1992, page 99:
I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: “Literate Programming.”
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.
With our model, there are at least three classes of user who need explaining to. One is me, in six months’ time after I’ve forgotten how my code worked. The second is my colleague. And the third is the economists and others who will use the model.
This final class need a little extra help. My networks can be seen as a kind of literate program where the expository narrative is branched rather than linear, and the essayist is writing around function definitions rather than equations. Traditionally, economic models have been opaque, their assumptions known only to the few who implemented them. But with this kind of display, everyone is free to peer inside.