The code samples for the subject I’m teaching are all written in Literate Haskell. Having worked with a bit of this code, I can say it’s a complete nightmare. The Wikipedia article discusses the philosophy behind it — I’m not here to debate that. My criticism is primarily that literate programs are god awful to work with in a text editor.
What I’m talking about is a programming style (specially supported by the Haskell language) in which comments are the default, and if you want code, you need to explicitly delimit it with a “>”. It inverts the comment/code relationship so that comment is the default. It means that instead of this:
-- This program calculates the factorial of a number. fact 0 = 1 fact n = n * (fact (n-1))
You write this:
This program calculates the factorial of a number. >fact 0 = 1 >fact n = n * (fact (n-1))
I’ve compiled this list of gripes after working with this style for just a few minutes:
- It encourages extremely verbose comments. This seems at odds with the programmers’ mantra that “good code is self-documenting” and therefore, ideally, code doesn’t need comments at all (except to briefly explain what each function does, and explain any tricky bits).
- Text editors don’t highlight the comments (as I demonstrate above). At least vim doesn’t. As far as I can tell, this is by design — the idea is that the program is actually an essay with code snippets, and thus you wouldn’t want the majority of the characters to be blue/green.
- You have to write a > on every line of code. I find this much more annoying than having to write a “–” on comments, possibly because when I’m coding, I need to concentrate more than when I’m just writing English.
- Working with code is a nightmare. The main reason is that code is indented. So if you forget to add a > on an indented line, you have to go to the left and add it, then you’ve offset your line by 1 character and have to fix it up. If you join a line (Shift+J in vim), it won’t nicely delete the indentation from the subsequent line, because there’ll be a “>” in the way followed by a lot of spaces. You spend a good percentage of your time messing about with “>” characters.
- Can’t use line or block indentation commands (such as Shift+> in vim to indent the current line or block), as they’ll indent the > (which must be in column 0). Shift+< doesn’t work either, as vim considers all lines to be unindented. You have to put the cursor at the real start of each line and hit tab.
- Shift+^ no longer takes you to the start of the line; it takes you to column 0.
- Forgetting a “–” usually means a syntax error. Forgetting a “>” means a missing line of code, which may or may not generate a compiler error (could be a missing pattern, for example, which is a runtime error in Haskell).
This could be a useful style for writing an actual essay with code snippets, but not for an actual program.