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:

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

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.

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.