On 2 May 2014 18:08, <d...@axiom-developer.org> wrote: > > Writing "just the code" is about as effective as a book containing > only the physics equations with no text, correct but opaque. >
A physics equation doesn't completely describe a system. A program does. Any software designer worth his title would first collect requirements. > Collecting requirements assumes you know what you're looking for. In this case it seems wiser to experiment. I know that some people dismiss literate programming "by fiat" (aka > it is worthless..., it can't work..., it adds nothing..., etc) but > surely Knuth is a "Deep Thinker" on par with Rich Hickey. > A lot of the praise for literate programming, including the quotations you provide, is that it's a way of helping the original author understand the software they're writing. But as a form of *documentation,* I'm not convinced literate programming has much worth. When I approach a new library or tool, I typically find myself in one of three states: 1. I understand the concept of the library, but need a reference. 2. I don't understand the concept of the library, and need it explaining to me. 3. I want to know how the library works internally. For the first use-case, what I'm after is an index, like Autodoc or Codox. A literate program isn't particularly good for this, because it follows a linear narrative. For the second use-case I want an in-depth description of what the library does, along with plenty of examples. Literate programming fits this case a little better, but isn't geared up around the idea of providing example code. Literate programs show you what the program does, but not necessarily how to use it effectively. The third use-case is the only time literate programming makes sense, but it's also the least used of the three. I'm also not hugely convinced it's actually much use - whenever I read literate programs in Clojure I find myself skipping down to the code, as it's actually easier for me to read the code than the English text accompanying it! And is that such a surprise? Computer languages are designed (or should be designed) for readability by humans. They're a specialised language for describing code to other people, and only incidentally executable by computers. If execution of code was all we cared about, we'd be writing assembly. I'm also of the opinion that programming languages are far more expressive today than they were back when Knuth originally came up with the idea of literate programming. - James -- 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.
