There’s been some recent discussion on ruby-talk about “literate” programming after the new O’Reilly title Beautiful Code was announced (Matz has written an essay for it). Matz’s response made me listen to all-things-Knuth, so I was pleased to read Philip Wadler’s post today on Three ways to improve your writing, which includes a PDF link to Knuth (and others) lecturing on writing and “literate” programming. I’ve just started reading it, but have already found two laugh-worthy gems:
13. Many readers will skim over formulas on their first reading of your exposition. Therefore, your sentences should flow smoothly when all but the simplest formulas are replaced by â€œblahâ€ or some other grunting noise.
20. Some handy maxims:
Watch out for prepositions that sentences end with.
When dangling, consider your participles.
About them sentence fragments.
Make each pronoun agree with their antecedent.
Donâ€™t use commas, which arenâ€™t necessary.
Try to never split infinitives.
I know the first is certainly true for me as I’ve been trying to wade through Haskell (a language into “literate programming”) introductions recently, which are very math-heavy.