Literate Programming
December 25th, 2005
Literate Programming, or LP for short, is this wonderful idea that instead of writing computer programs with embedded comments, we write documents with embedded programs. This seems like a great idea and it is, but it seems to be universally poorly executed.
First there is the original CWEB, the LP system invented by Knuth to write TeX. The idea is to embed C/C++/Java fragments into the main TeX body of the article or report. This is nice because (almost) everyone agrees that (La)TeX is the nicest thing to write technical documents. And its revision-control friendly as well. However, trying to read a CWEB document is quite painful and mainly seems to consist of lots of `@’ symbols.
Then someone simplified and came up with noweb, but it seems to suffer from the same sort of `@’-itis.
Various people seem to have tried, at one time or other, to define LP schemes based on XML, but they end up looking even worse than CWEB.
Why is this nice concept so hard to translate into practice? Certainly one reason is editor support – the code fragments need to be highlighted and indented the same way as it would be if I wasn’t using LP. Currently with the emacs CWEB support this isn’t the case. Another reason is the evolution of code: I want to be able to write a report for each change set I make to the code. That doesn’t mean I want a report for each commit, but for each consistent set of changes, explaining the functions of new classes and files, but also the changes to old ones. This means my LP system needs to handle partial files and documentation as well.
Perhaps it would be better to include the documentation within the comments within the source, similarly to JavaDoc/Doxygen. The LP system would then have to be aware of the language, recognising documentation before classes and functions as different from that within the code body.
Maybe LP is entirely unnecessary if we all just commented a bit better?
PS: Happy Christmas!