Shane Cellos has a nice post on why literate programming makes sense. He tells the story of how he and an equally matched colleague worked on a relatively simple project. It was, he says, an ideal situation. One colleague with a similar technical background. What could go wrong?
You can read Celis’ post to see what went wrong but the TL;DR is that the code quickly diverged from the spec and only one of the researchers understood it. Celis suggests that using literate programming to document what the code is trying to do would have made the collaboration easier.
I’ve been coding so long that presenting code in its natural order seems like the right way to me so I don’t feel the need to document the code in an order different from what the compiler sees. That said, I think it makes a lot of sense to write a document explaining the code in which the actual code is embedded in the document.
Of course, this is ideally suited for Org mode, which is what I would use, but others may find another method better. Regardless, we should all consider how literate programming can enhance our workflow. See Howard Abrams posts on Literate Devops for a fine example of this.