The thread on documentation that Val started ( https://groups.google.com/forum/?hl=en#!topic/clojure/oh_bWL9_jI0) is getting a little long so I'm starting a related one specific to litprog.
I've made a start on rethinking LP at https://github.com/mobileink/codegenres/wiki/Rethinking-Literate-Programming . A few key points: * Knuth's main early LP tool (WEB) was to a certain extent an attempt to fix deficiencies in Pascal, as Knuth himself explicitly acknowledged. Some aspects of Knuthian LP (KLP) may make sense for imperative languages with side effects; since it's hard to reason about programs written in such languages, added commentary is needed. But if you already know that functions are side-effect free and data are immutable, you no longer need that. * Programming language design has not evolved in the direction of LP, as we might have expected from some of Knuth's more grandiose pronouncements; instead they have evolved in the direction of greater expressivity, which obviates the need for many kinds of documentation. You can argue that LP was a fine thing in its day, but the world has moved on. * KLP is largely based on the personal aesthetic and psychological preferences of DE Knuth involving issues such as the proper order and mode of presentation of code. Those are normative issues, and there is no reason to take Knuth's preferences as gospel. In particular there is no justification for his claim that using LP "methods" leads to "better" code. It not only depends on what "better" means, it depends on what other methods are available. Just because writing Pascal in LP was better (for Knuth et al.) than writing plain Pascal does not mean this will always be the case in all languages. It doesn't generalize. (To a hammer, everything looks like a goto.) * There is (demonstrably) no reason to think that there is any "natural" or "best" order of presentation for code; there are only preferences, and everybody has one, if you catch my drift. The point again being that Knuth was not on to some kind of laws of programming. KLP is all about his preferred style, not about the Way Things Are. * KLP is sometimes contrasted with "self-documenting code" To get a grip on what that is and what we can expect from it we need to examine the notions of function, algorithm, and code. Then it looks like code does not in fact "self-document", if "documentation" is taken to mean explanation. But it does express meaning, and sometimes expressivity is preferrable to explanation. Maybe that's terminological nit-picking, but sometimes coming up with the right terminology makes all the difference (see "lambda abstraction"). * Speaking of which, Knuth himself admitted that his choice of "literate programming" as the name of his "new method" was tongue in cheek, since it makes anybody who doesn't use it an "illiterate programmer". (The citation is in one of the essays in his book "Literate Programming".) So maybe we should stop using it and come up with a more accurate name. Howsabout "Knuthian Programming"? * Knuth's model for program text is the literary essay, read from beginning to end. This is obviously in tension with the way code actually works. Library code usually does not have a beginning or end, for example. This is a little ironic, since hypertext has liberated us from the tyranny and oppression of linear narrative. A better literary analog to program text is The Book of Lists, or Commonplace books, whose contents can be read in any order. * Finally, a whiff of a hint of a soupcon of a concrete proposal: instead of supporting some kind of structured markdown-style syntax in comments and docstrings, add support for the Z specification notation, so that we can express in clear, concise, formally defined, standard set-theoretic notation the exact meaning of code. That's the general idea, I don't have a concrete suggestion yet. There's more stuff on the wiki<https://github.com/mobileink/codegenres/wiki/Rethinking-Literate-Programming>, and more to be said, but I'll stop here. Cheers, Gregg -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
