I will look like a complete Philistine, but this piece is my first serious exposition to literate programming. The times I had heard about this approach to software development, it had been derided as academical, unpragmatic and impractical -- something that was of interest only to its pioneer, Donald Knuth. That that I can see it for myself, I think the ideas behind literate programming are utterly exciting.
Not that I think that the piece above got it completely right. Actually, its takeaway should be "do as I say, not as I do." The author hits his mark when saying that the text segments between the code fragments should explain the why of the code, not the what. Explaining the what is repeating oneself, as the code is the what. Still, the author goes off and writes about the what of his code and not they why, so his whole program is a bit hard to read, in spite of being simple and fully documented.
The what is the code. The why lives as a second, third, nth degree within the code. What the text between the code should say is why some variable is made global. Why some functionality is spread between these three processes, these five functions. Why these things are coupled, when we know coupling is bad. Real-life code gets ugly, as programming is like packing one's car trunk: you make decisions above decisions you've made previously from less information. It's NP-hard!
Literate programming done in increments, supported by unit tests, should then document the decisions as they are taken. This documentation can drive future debugging and refactoring, avoiding contradiction and easing new developers trying to wrap their head around the growing code base. I feel that literate programming is a complementary way to manage the complexity bloom of software projects.
Its now a cliché that programs are parsed by computers, but read by people. I'll add that if compilers have a right to complain that a program is unfit to be read, so should people. Programmers must communicate their ideas to people. They thus must be good writers. These days, we see many people embracing the functional programming languages and approaches that I had seen my coeds deride when we learned them in undergrad CS. FP is the old idea that's become a good, fashionable idea. I feel that the next such concept to resurface will be literate programming.
Unsatisfied with what the author of the paper above has come up with, I have been checking out modern literate programming weavers-tanglers. Being a LaTeX afficionado, and wanting to experiment with multiple target languages, I've settled on nuweb for my initial experiments. Feel free to share your own experience with LP in the comments.
