Greg, I can tell by the amount of work you've put into this document that this is an earnest attempt at analysis and not trolling, so I'm going to give you my earnest response: you are wrong on so many levels.
First, you seem to have several misconceptions about literate programming in general, and Knuth-style literate programming specifically, which makes me wonder whether you've ever actually read Knuth's code. For example, you say, "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." Yes, it is true that one goal of literate programming is to free the programmer to choose an order to describe the code that is independent of the order and structure that the compiler needs to see it. But a Knuth-style literate program is far more than a linear essay. Although you *can* often read a literate program from beginning to end in order to understand the full system, the detailed hyperlinking and indexing makes reading code almost more like a choose-your-own-adventure story, making it easy to understand the parts of code you care about and understand how the different parts relate to one another. I suggest you sit down and read some actual Knuth code if you want to try to understand what that approach does and does not accomplish. Second, you repeatedly make the case that programming expressiveness (and presumably Clojure's expressiveness specifically) is far better than in Knuth's time. This is nonsense. LISP is one of the oldest languages, and Clojure isn't profoundly different in its expressiveness. In fact, Clojure has a number of features that actively hurt its expressiveness relative to other modern languages: 1. Definitions must precede their usage. Can usually work around this with forward-declarations, but even that small extra burden causes programmers to tend towards a bottom-up style of writing Clojure code, even if that is not desirable for a certain program. 2. Very strict limitations on ways that different files/namespaces relate to one another (e.g., no cyclic dependencies), so very often, things need to be organized for the convenience of the compiler rather than for understanding. 3. Limited convenient notation for expressing that a function is merely a "helper function" (only defn has a convenient notation for this, defn-). 4. The tooling convention of having tests in separate files places even more obstacles in the way of using things like defn- in order to express the distinction between primary and secondary functions. 5. Clojure's inability to handle local recursive references (i.e., no letrec) provides obstacles for clearly expressing that certain things are merely local functions/data for another function. Some things have to be made global that conceptually aren't. 6. The "sea of sameness" problem -- no visual distinction between functions, macros, variables, control constructs. You state that functional programs are so much easier to comprehend than mutable ones, they don't really require explanation. This also is silly. I challenge you to buy this book: http://www.amazon.com/Pearls-Functional-Algorithm-Design-Richard/dp/0521513383, a collection of literate programs (in the academic article sense of the word, not really in the Knuth sense) written in Haskell, arguably the "most functional language". Most of the chapters conclude with the entire source of the program under discussion. I challenge you to pick any one of those chapters and look just at the final program, then try to figure out how and why it works. Good luck! There is a reason why academic computer science journals are not just books of raw source code. Innovative code and complex code require explanation. I would argue that Clojure would not exist were it not for a long tradition of code-embedded-in-detailed-explanation. Clojure is founded on the use of cutting-edge functional data structures, and I would wager that Rich Hickey would likely not have understood these structures well enough to implement them so successfully had he not been able to read articles explaining their construction and why they work. So this notion that the world is trending away from literate programs just isn't true. We see them all the time in the form of articles and blog posts designed to elucidate, we see them all the time in the context of real-world large, complex systems designed to outlive the people who created them, and in the context of literate programs written to teach and influence a new generation of programmers. For example, did you know that the book/literate program "Physically Based Rendering" recently won a Scientific and Technical Academy Award? (Yes, that's right, a literate program won an Academy Award -- the "Hollywood movie" kind.) "Physically based rendering has transformed computer graphics lighting by more accurately simulating materials and lights, allowing digital artists to focus on cinematography rather than the intricacies of rendering. First published in 2004, Physically Based Rendering is both a textbook and a complete source-code implementation that has provided a widely adopted practical roadmap for most physically based shading and lighting systems used in film production." If you don't ever write algorithms that would be easier for others to understand if you could include a picture or a mathematics formula, that's fine. If you don't ever write code that would benefit from being presented in an order independent of the constraints of the Clojure compiler, that's also fine. If you don't write code where the reasoning behind the code needs to be understood deeply by other programmers who will follow you, that's great. The truth is that there is a lot of programming out there that needs to be done -- programming which is so obvious that almost any programmer would sit down and approach it the same way -- programming that requires little explanation. Maybe that's the programming world you inhabit, but you need to recognize that not everyone inhabits that world. For example, I personally don't inhabit the world of programmers who need to *prove* their programs are correct. But I don't go around denying the value of formal verification systems. I could truthfully make claims like, "One obstacle to formal verification is that it is difficult to constantly update the verification proofs in real-world programs with aggressive schedules and constantly changing requirements. There's a reason why formal verification hasn't caught on in everyday use -- it's hard. You have to understand programming *and* proofs." However, none of those claims would eliminate the value and validity of that approach to programming. Similarly, it is true that literate programming faces genuine obstacles to mainstream adoption: it's hard and doesn't (currently) integrate well with the other tooling we use. In fact, I've heard exactly the same claims leveraged against functional programming (it's hard and doesn't integrate well with debugging and other analysis and refactoring tools that are commonplace in languages like Java). But that doesn't mean there isn't value there. Even if you don't personally see the need for literate programming, anything that moves us in the direction of incorporating richer text, images, hyperlinks, video, formulas, auto-updating examples, etc. into our programs is a good thing. One problem with the "journal article" model of literate programming is that it tends to involve prose written around a finished, unchanging program. Any new ideas that help strengthen our ability to build explanations around living programs is a good thing. I recongize there are challenges: it's very hard to figure out how to do this in a way that will work across all the tools and IDEs that are common in the Clojure community, but I applaud the efforts of those who want to make these problems easier in Clojure. -- 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.
