16

I'm new to the concept of literate programming. I was reading Donald Knuth's paper (PDF) concerning this subject, and in the very beginning, in the Introduction, he says:

Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

He or she [the practitioner of literate programming] strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.

Then, reading further:

A thing about a program is its structural relationships. A complex piece of software consists of simple parts and simple relations between those parts; the programmer’s task is to state those parts and those relationships, in whatever order is best for human comprehension— not in some rigidly determined order like top-down or bottom-up.

(...)

Top-down programming gives you a strong idea of where you are going, but it forces you to keep a lot of plans in your head; suspense builds up because nothing is really nailed down until the end. programming has the advantage that you continually wield a more and more powerful pencil, as more and more subroutines have been constructed; but it forces you to postpone the overall program organization until the last minute, so you might flounder aimlessly.

Thus the WEB language allows a person to express programs in a “stream of consciousness” order. TANGLE is able to scramble everything up into the arrangement that a PASCAL compiler demands†. This feature of WEB is perhaps its greatest asset;

The above excerpt make me interested in the subject, so I investigated a bit more. It's not difficult to see in the results provided by any search engine the relation between Haskell and literate programming, but I don't see the that “order best for human understanding”. Rather I see a very well done documentation while keeping the order that the computer requires in order to work.

  • Can you use the term “literate programming” taking away that order issue?
  • Is there any other definition of literate programming that do not requires the "stream of consciousness" order feature?
  • Is Haskell really literate programming capable (using Knuth’s definition)?

Last, I have to say as a personal opinion, that even what Haskell does (and probably many other languages do) is not Knuth's literate programming, I still like the idea when it comes to exhaustive descriptions of methods and algorithms. When the comments exceed by far the code it serves a great purpose.

† WEB and TANGLE are part of the system that originally D. Knuth used in his first implementation of the literate programming concept.

Community
  • 1
  • 1
J. A. Corbal
  • 936
  • 9
  • 20
  • 1
    At the top level, Haskell expressions can be in any order (even within functions you can order things however you like with clever use of `where` and `let`). So if you have an exceedingly complex module, you can express the main idea first, which may depend on definitions below it, explain that main idea, and then go on to decompose it into its parts below that. – user2407038 Jun 01 '13 at 04:51
  • At the time Knuth designed TeX with friends he chose the Standard Pascal compiler as the code generation target. Standard Pascal is very strict about how it wants things served (which was to get a single-pass compiler) so it is hard to write code as prose. Modern languages like Haskell are much more lenient making it mostly a matter of how to mix the runnable code with the documentation. – Thorbjørn Ravn Andersen Dec 27 '20 at 07:17

1 Answers1

16

Haskell is, for the most part, very flexible when it comes to ordering. Within a Haskell module, all declarations and definitions may occur in any order. Thanks to referential transparency, it is also very easy to extract subproblems in order to implement them somewhere else.

The main area where order matters is pattern matching. All equations of a function have to be together and since they are matched in order, they cannot always be re-ordered. However, I do not feel that this is a significant limitation since (a) this is usually very localized and (b) big functions with lots of equations can (and probably should) be refactored into smaller parts which are then easier to re-order.

The perhaps most annoying constraint is that import declarations have to be at the top of the module. This does break the stream of consciousness a little, and many literate programs written in Haskell begin with a statement like "don't mind these imports, you'll see where we need them later". It would have been more consistent with Knuth's definition of literate programming to be able to name imports at more natural points during the text where it is clear from the context why they are needed.

That aside, I think Haskell works well for literate programming. It may not fit Knuth's definition perfectly, but I think it comes close enough.

hammar
  • 138,522
  • 17
  • 304
  • 385
  • 8
    I've always wondered why `import` statements need to be at the top of the file. – Gabriella Gonzalez Jun 01 '13 at 05:52
  • Couldn't you just have a preprocessor that handles that stuff though? Isn't that basically what CWEB does? – Wes Jun 01 '13 at 08:46
  • 2
    @Wes: Yes, that's basically what CWEB does. But there is a great advantage to have support built into the language and the compiler, and I don't think literate programming would have become as popular as it is within the Haskell blogging community without it. And it's all familiar Haskell syntax. You don't have to learn CWEB's syntax on top of it. – hammar Jun 01 '13 at 09:06
  • @wes a preprocessor introduces additional complexity because you really want the various toolings to know that you have an original document and not just the modified copy generated by the preprocessor. Editing a different file than you should happens much too often. – Thorbjørn Ravn Andersen Dec 27 '20 at 07:20