>Hm. Maybe I should ask this off-list, but, in a nutshell, is literate >programming:
I feel this is an "on-list" topic (although it is obvious that I'm an edge-case fanatic). Clojure is trying to introduce a lot of new ideas that change how programming is done. It is an edge-case community. I'm trying to change the standard to which Clojure programs are written by introducing a shiny, new edge-case idea (from the 1960s). High quality Clojure programs should be literate. > > 1. put possibly-out-of-order specially-marked (with an id) code snippets >throughout your doc, > 2. also put an *ordered* listing of all the id's somewhere in your doc, > 3. use tools to find that ordered list of ids, then extract the snippets, >put them in order, and glue them all together so they can be compiled/run? Programs are written in a certain order because the compiler requires it. For instance, some code in Clojure is required to occur before others (e.g. importing code, pre-compiling java). If you try to explain various ideas and illustrate them with the REAL code that will be EXECUTED you need to be able to arrange the code in human order, not machine order. Most documentation tools (javadoc, doxygen, org-mode, etc.) associate the explanation with the code rather than associate the code with the explanation. This prioritizes the machine over the human. But the point of explanation (not documentation) is to communicate to a human. These tools miss the point. A literate program emphasizes human communication over machine communication. Thus code is introduced in human order. Look at the book "Lisp in Small Pieces" to get an idea of how well it can be done. A good explanation starts with motivation. Any writing course emphasizes "finding the motivation for the character's actions". In explaining Clojure, for example, you'll find that the motivations are usually brought forth in a Rich Hickey talk. He talks about the motivations for immutable data structures, for time and state, for carrying metadata, and so much more. None of this is in the code base. If you don't know about immutable data structures then the code that implements lists is completely inefficient nonsense. It would traditionally be seen as hanging onto nodes that are "dead" for no apparent reason. Lacking the motivating explanation any good programmer would "optimize away" all the cruft, breaking Clojure. So to explain something to a human you need to motivate it. To motivate it you need to arrange the thoughts in the proper order. In a literate program the thoughts are "reduced to practice" by showing the actual code inline. This implies the ability to re-arrange code to suit the human. Ultimately, think of writing code as though you were writing a book. Let the code fall where it fits best in the chapter where it belongs. Now you have a work of literature that communicates to a human. That, I claim, will keep your program alive after you abandon it. Give someone your program. Send them to Hawaii on a 2 week, all expense paid vacation. If, when the return, they can maintain and modify the code as well as the original developers then you have written a literate program. (aka "the Hawaii test"). Tim Daly -- -- 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/groups/opt_out.
