7.3. Literate Programming

Literate Programming is a method of writing code that allows one to intermingle code with documentation, re-order the sections of the code in relevance to their intention, and create an entire document typeset that is explaining the code, with full cross-references and interlinks. As Mark Jason Dominus explains POD is not Literate Programming.

Traditionally, Literate Programming systems have generated TeX/LaTeX output, but more recently there have been ones that could output DocBook/XML.

I am personally not writing my code in a Literate Programming style, because I feel that:

1. It will require much more effort to create code that will only be marginally easier to understand.

2. The documentation will need to be maintained along with the code and may become out-of-date. Even inline comments suffer from this symptom, and external documentation much more so.

3. The code should be structured to be as self-documenting as possible. For example, instead of documenting what a block of code is doing, one should extract a subroutine with a name that conveys the intention.

However, I'm mentioning Literate Programming here for completeness sake, should you choose to follow this route.