> PS. Just to be clear, my purpose is neither to attack nor to defend LP, > just to get clear about exactly what it is, what its presuppositions are, > what its implications are, etc.
I also do not want to get into defending LP yet again. But I do think you might have missed the key point by focusing on presentation rather than communication. > * 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. Having worked in string-free Pascal, the only real way to "fix it" would be to take it outside and burn it. :-) > * 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. "The nature of functional programming is to build, Russian doll-style, functions that use functions that use functions etc. But without something like a literate style, your efforts are quickly lost in the details. You do stuff -- and unless you have a phenomenal memory, you've simply dug a nice, deep tunnel that is, at the same time, collapsing behind you. YOU may know what you've done, but how to make others aware and get them involved? All they see is some collapsed tunnel with a sales pitch about how you should go re-dig that very same tunnel." -- Lawrence Bottorff, February 2014 > * 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.) While the "proper order and mode of presentation" is a matter of personal preference it is not really germaine to the problem. When code is written and decorated with comments about what it does we feel we have communicated the important part. The problem is that we missed the "why". Sure, we have immutable, log32, red-black trees (ILRB trees). Yes, we documented what the arguments mean. But you'll notice that nowhere in the github tree is there any answer to "why?". A "literate programming style" isn't really the issue. The loss of "why?" is the issue. Answering "why?" means that you have to build up the background problem so people can understand "why?" the code is a solution. In other words, you need to communicate the ideas in some linear fashion so they have a common background understanding. > * 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. As an author I agree that there is no "natural" or "best" order of presentation. But there are clear preferences. Pick up any "book" which is a collection of conference papers and you can see that presentation choice is vital. Random, unorganized piles of ideas is not communication. The real focus of literate programming is actually about communication from one person to another. "Ideas" are missing from "The Way Things Are". At best we document what something does but not why we want to use it. If you look at the mailing list, a lot of the answers are of the form "this is why you should write it this way". Rich has been pretty good about communicating his ideas and his videos can be found on the web, assuming you know where to look and what you are looking for. Which video would I watch to get the ILRB tree concept? Which one would I watch to get the ideas behind "conj vs cons"? Or the details of software transactional memory? Where is the explanation of that long block of code I posted last week? And how do those ideas relate to the code? After all, I end up staring at the code. > * 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"). "Self-documenting code" is known as Cobol. Expressivity IS preferrable to explanation as anyone who does comedy or art knows. Explaining a joke ruins it. I can't say the same for explaining code though. The "right terminology" is definitely important. But reducing the idea expressed by the terminology to a single symbol assumes that there is shared semantics between the author and the audience. A sliding_window variable is useful in TCP code but meaningless unless you have the background knowledge to capture the semantics. > * 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. I have several "book of lists". My chemistry list will tell me everything about hydrogen. My biology list will tell me all about glycogen. My physics list will tell me all about momentum. They can be read in any order. The problem is that communication requires orderly and logical development to build concept upon concept. I see you've created a wiki. The wiki idea is that everyone can contribute and that the information will self-organize. In my experience with two projects that were wiki-based I have found that the information may be somewhere on the wiki. Unfortunately the information doesn't "self-organize" in any rational way. Both wiki efforts reached a "wiki horizon" where they became chaotic. Anyone could point at the wiki saying "the information is here", since they wrote it. But no other person could find it. As any author of a textbook knows the hard part is linearizing the information so it can build upon itself. Everybody needs to know everything to understand anything and it falls to the author to choose a path, lay the foundations, and communicate the ideas in an orderly and logical fashion. > * 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. I have used ACL2 and COQ to write formal specifications of code. If you think literate programming is painful and opaque you have to try to read these proofs. I do support the idea of program proofs but you REALLY don't want me to climb on THAT horse. I'm being enough of a pain already. Curry-Howard would get me lynched. :-) I think that there is a hierarchy of things we can do to make Clojure code better and these can be ordered by how much "machinery" we need to make it work. A possible order might be Geekhood 0) read the code Motherhood 1) good variable name choice Javadoc 2) docstrings 3) argument type decorations 4) API coverage Markdown 5) paragraphs explaining code ?? 6) sections explaining ideas ?? 7) chapters introducing areas ?? 8) table of contents 9) index 10) bibliography ?? 11) hyperlinks ?? 12) inline executing examples (e.g. running Ant inline) 13) audio 14) video Having travelled this path I found that LP using Latex covered all of these cases using only one tool. Clearly other people would like a collection tools aimed at the specific problems. The choice isn't really important but the goal of better communication is. Tim -- 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.
