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