Re: [Axiom-developer] Literate Programming example

[Daniel Jomphe]

On Saturday, November 19, 2011 2:37:48 PM UTC-5, TimDaly wrote:

However, as Knuth points out and as I've already experienced, writing
a program in literate form vastly reduces the errors. There are two
causes I can find.

First, if I have to write an explanation then I have to justify my
poor code hacks. Sometimes I find that I rewrite the code because the
very act of explaining the bad code made me realize that the code is
bad. I find I have to talk about memory allocations so I catch leaks.
I have to talk about argument handling so I end up proving that the
arguments are correct, or I end up checking for possible failures.

Second, because other people can see the reasoning at the code review,
they can chastise me for failing to explain, or explaining things that
the code does not do, or just plain failing to implement a correct
solution.

With the tools available to us today, there's no reason why we at least shouldn't have everything needed to make literate programming more seamless, more natural. For example, while reading your toy example, I found myself wanting to ask a question or comment on your thoughts a few times. If your book had been displayed on a dynamic website geared towards literate programming, I might have been able to click on a paragraph and write my question/comment right there. And then, after a short conversation there, you would have integrated the fruits of our conversation directly into the end result. Thus each new reader would have been an occasion to improve the book. ...It's nothing surprising since this kind of review system already exists in some publishers' toolkits.

Another thing that appeals to me regarding Tangle, is the fact that it may be used to keep things DRY. For example, when we have many arity-overloaded implementations of a function, some of their arguments are repeated, and we need to duplicate their api docs. Tangle could be leveraged to get rid of this duplication.