Hello, 2011/11/19 TimDaly <d...@axiom-developer.org>
> On Fri, 2011-11-18 at 20:02 -0800, Daniel Jomphe wrote: > > On Friday, November 18, 2011 7:17:08 AM UTC-5, TimDaly wrote: > > Many of you asked me to show an example of a literate > > program and demonstrate the use of the tangle function. > > > > I usually use Latex for literate work but I've done > > this example using HTML and <pre id="foo"> tags. > > > > I've written a self-referential literate program that > > explains the details of the tangle function in literate > > form. You can find the web page at > > > > http://daly.literatesoftware.com/lithtml/litprog.html > > > > I have read your literate program, and must recognize that I know how > > tangle works even though I didn't want to really read the source code. > > I read your prose all the way through. I still haven't read the source > > code; > > In fact, that's the whole point. You don't read the equations in a > calculus textbook either. You read the words. The equations are icons. > If you understood the text and "spoke" mathematics you could probably > write the equations. > > In programming we can reach the same level of literacy. Reading just > the words in the literate version it should be possible to recreate > the program in your favorite language. Note that you would be creating > a different program with different design decisions but the same > functionality. > > > I didn't feel the need to read it. Were I to maintain your program, > > I'd have more than enough confidence to start hacking the code right > > now. > > One thing worth trying would be to code the same program in Clojure. > > The tangle program is conceptually very simple but there are a lot > of low level design decisions that I would make differently. For > example, there are loops in the C program which would go away. > > Would you map read or would you slurp? Mapping a read function allows > transforming "& lt;" to < at read time. This does not matter in the C > program because the buffer is mutable but it would matter in Clojure. > > Would you use the Clojure pattern language to find the <pre> tags? > Would you be able to parse out the string from the id? C encourages > character-level hacking but Clojure would be much more powerful. > > > > > > > I think this speaks very positively about literate programming. What > > remains to be seen is how much (or not) I'm going to practice it in > > the future. > > If you do try to rewrite it in Clojure please post the program. I > would be very interested to see how Clojure's concise syntax and > semantics get reflected in your design decisions. > > The tangle program in Clojure might turn out to be a single > s-expression of only a few lines. The code density would be a > huge win but a literate version would still have to have the > vitals of the story. Remember that the key test for a literate > program is the "independence test". Someone can read it without > talking to you, understand how it works, and be able to change it. > > > > > > > What do you think of marginalia? It's a bit the reverse of tangle; it > > assembles all those 70's files together into this book you might want > > to read. Is it sound or not? Have your thoughts changed from what you > > wrote in [1]? > > > > > > [1] http://goo.gl/cXWzF > > Literate programming is a mindset, not a tool. You can write a > literate program in anything, including marginalia. > > That said, I have yet to see a Clojure program that lays out a story > so I can sit and read it. For a real challenge, if you try to write > tangle in Clojure, try writing the story in marginalia. I'm sure > Fogus would welcome the feedback. > > > The readability aspect is a real feature. Heck, you could even give > your programs to a company so they could read them BEFORE the job > interview. I would strongly favor hiring someone who could > communicate, who cared about code quality, and who could improve > the company's maintenance headache in the long term. A Literate > Clojure programmer would be a real gotta-hire person. Companies > use many programming languages but all programmers really do need > good communication skills. > > > In the long view, it would be sweet if the Clojure reader knew how > to read a literate program. Just call "(literate-load file chunk)" > and you get the same effect as if you had tangled the program to > a file. > > With literate-load available you would be able to write all of > your Clojure code in a literate style, making Clojure much > easier to understand, maintain, and modify. > I'd be interested in studies proving that programs written in a litterate style are easier to maintain. So far, there has been this metaphore between a "story" and a "program". How far can this metaphor be pushed ? Is it easy to write a book with more than a couple people ? To maintain it ? To modify it ? I can easily understand the appeal: if I were to discover a program for the first time, I would certainly be interested in discovering it via a literate style, because I would have some guarantee that some effort has been pushed into providing for the mainteners: contexts, argumentations, debates concerning design choices, etc. But past this first "introduction" to the program, I don't know what it would cost to maintain it without adding to the entropy of its literate part. I mean: to be honest, it's not as if, already, all programs written were correctly documented and we were facing a wall: "we can not improve our documentation further, we need to find another way to document our programs" ;-). Sorry to have to play the role of the devil's advocate, but I think there are currently holes in the argumentation in favor of literate programming, at least wrt to the material I've been exposed to so far ... > > > > 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 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
