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

Reply via email to