puzzler and Tim,

  Well said, gentlemen. As someone who has been using LP heavily for the 
past two years, I have certainly reaped many if not most of the benefits 
regularly argued in its favor (and of course, I've wrestled with all the 
usual tooling issues as well). While I agree with puzzler that many 
programmers probably don't write sufficiently novel software that would 
benefit from an LP style, quite a few of us do. In my case, much of my 
programming is aimed at environmental research, developing models and 
algorithms for describing and predicting natural processes and human 
interactions with them. In order for my work to be accepted and used for 
decision making (usually around land planning), it is absolutely crucial 
that I can transparently explain all the formulas used, literature cited, 
and conceptual steps taken to get from empirically measured data to 
modelled outputs. A literate programming style not only helps me to 
organize my thoughts better (both hierarchically and sequentially), but it 
provides me with a living (tangled) document that I can share with my 
non-programmer colleagues to get their domain-specific feedback about my 
choice of model assumptions, formulas, etc. This enables a level of 
collaboration that I simply could not achieve if I simply wrote the code 
directly. Finally, as a thoroughly unexpected side effect, some of my most 
complicated programs actually became much, much shorter when I rewrote them 
in an LP style (in terms of lines of code, of course). Part of this had to 
do with the available tooling (Org-mode's polyglot literate programming and 
reproducible research facilities are outstanding) and part of it simply 
came from having to write down my ideas in English first. This kept me from 
rushing into writing code and possibly getting lost in those "collapsing 
tunnels" to which Tim alluded. Instead, the additional "hammock time" that 
I took to think my way through how to present my solutions frequently led 
to "Aha!" moments in which I realized a simpler way to express the problem. 
Cliche, I know, but still results are results.

  Get Literate! (use only as necessary; LP may not be recommended for some 
patients due to increased blood pressure and carpal tunnel risk)
    ~Gary


On Thursday, May 8, 2014 8:57:51 AM UTC-4, Gregg Reynolds wrote:
>
> 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.

Reply via email to