literateprogramming.html

极限编程 Extream Programing

With some carefully constructed templates for certain tasks, and a little pre-processing, I find I can feed my Literate Programs (and I do virtually everything significant that way, since it helps me think better about the code) to hypertext-style index generators (a.k.a. "documentation generators", which I think is a dangerously misleading term).  My readers therefore have both approaches available for my code: the original story in context, and the ability to zap around at random.
--- Simon Clift
<hr>
I second everything Kent said.  Perhaps my misunderstanding about Knuth's writings, but the literate programs of his I read looked like the program was still sequenced for his compiler, with lots of English written around it.  That meant the English read to me like it was sequenced for his compiler.  I should like to see an example sequenced for me, with the pre-compiler so adapted as to straighten the code out for the compiler.  <a href="http://c2.com/cgi/wiki?AlistairCockburn">AlistairCockburn</a>
<p>
<em>I think you misunderstand Knuth's concept of literate programming. An absolutely fundamental concept of literate programming is that the program is sequenced for the human reader and not for the compiler. Most literate programmers consider systems that do not reorder code to not be true literate programming systems.  You may not approve of the order of presentation in <a href="http://c2.com/cgi/wiki?TexTheProgram">TexTheProgram</a>, but it certainly very different from the sequence in which the compiler sees the code.  For more detail, see Knuth's original article &quot;Literate Programming&quot; in his book of the same name, especially the section &quot;Programs as Webs&quot;. -- <a href="http://c2.com/cgi/wiki?DanSchmidt">DanSchmidt</a></em>
<p>
Consider a tour through the <a href="http://c2.com/cgi/wiki?HyperPerl">HyperPerl</a> version of Wiki
(<a href="http://c2.com/cgi/wikibase?WikiInHyperPerl">http://c2.com/cgi/wikibase?WikiInHyperPerl</a>).
It seems to me to be quite well sequenced for reading.
Ward also provides a script to flatten <a href="http://c2.com/cgi/wiki?HyperPerl">HyperPerl</a>
out into straight Perl.
The result seems to be sequenced more for the machine,
and provides a distinctly different reading experience.
--<a href="http://c2.com/cgi/wiki?DaveSmith">DaveSmith</a>
<hr>
I haven't looked very closely at <a href="http://c2.com/cgi/wiki?TexTheProgram">TexTheProgram</a>, but I have to agree that
starting with the lexical analyzer isn't a very good idea.  But hey, what do you
expect from the first one to do it?
<p>
Just yesterday I was hacking on a small literate (NoWeb<a href="http://c2.com/cgi/wiki?edit=NoWeb">?</a>) program, and found the
structure of the program-as-text (HTML, at that), to be at least noticeably
different from the program-as-code.  Part of this comes from attempting to
apply <a href="http://c2.com/cgi/wiki?CodeUnitTestFirst">CodeUnitTestFirst</a>.
When you apply this naively, you end up with sequences of test
and code interspersed.  Still may not be exactly easy to read, but it does give a
better understanding of the program's evolution, and to some degree it breaks
the program up into functional behaviors even if those behaviors are spread
throughout the code.
<p>
For example, my next &quot;unit test&quot; was to add line numbers to the output of my
program to indicate where the match occured.  Even though tracking the line
numbers and printing them out live in somewhat different places in the
code, the literate program puts all that stuff together.
<p>
Now, if only NoWeb<a href="http://c2.com/cgi/wiki?edit=NoWeb">?</a> could handle putting multiple source files into separate
HTML files and still have them indexed....
<p>
-- <a href="http://c2.com/cgi/wiki?BillTrost">BillTrost</a>
<hr>
Isn't literate programming kind of anti-<a href="ExtremeProgramming.html">ExtremeProgramming</a>? When your code is getting constantly refactored and written to communicate well, available in a browser, and has
tests that serve as examples, you might be better off just describing the system architecture, a few patterns, and perhaps a <em>how to read this program</em> and away you go.
I found Knuth's examples hard to read, but the Hanson and Fraser compiler book was a good example. Kernighan and Pike's UnixSystemProgramming<a href="http://c2.com/cgi/wiki?edit=UnixSystemProgramming">?</a> also contains excellent examples of code xposition, particular their example of <em>hoc</em>, an ad-hoc calculator. (PS. I wrote up some observations about programming and documentation in a paper[<a href="http://choices.cs.uiuc.edu/sane/home.html#readexpect">http://choices.cs.uiuc.edu/sane/home.html#readexpect</a>]). -- <a href="http://c2.com/cgi/wiki?AamodSane">AamodSane</a>
<hr>
See also <a href="http://c2.com/cgi/wiki?SelfDocumentingCode">SelfDocumentingCode</a>.
<hr>
For me, <a href="LiterateProgramming.html">LiterateProgramming</a> is more about SelfCodingDocuments<a href="http://c2.com/cgi/wiki?edit=SelfCodingDocuments">?</a>
than <a href="http://c2.com/cgi/wiki?SelfDocumentingCode">SelfDocumentingCode</a>!
It seems (to me) to be about writing a mathematical
and scholarly essay about solving a given problem, and then letting a program
generate (1) running code and (2) a paper about the problem and
its solution.  
<p>
--<a href="http://c2.com/cgi/wiki?DickBotting">DickBotting</a>
<hr>
<a href="LiterateProgramming.html">LiterateProgramming</a> may be anti-XP in some ways, but some of the motivation is very similar. For instance, one benefit of <a href="PairProgramming.html">PairProgramming</a> is that you have to explain everything. This greatly reduces the amount of fuzzy thinking you can get away with, and helps to eliminate bugs. (This is why RubberDuckDebugging<a href="http://c2.com/cgi/wiki?edit=RubberDuckDebugging">?</a> works.) One of the main points of <a href="LiterateProgramming.html">LiterateProgramming</a> is that as you go you're explaining what you're doing for the benefit of an (unspecified) future reader. Same point, no? I think there's room for both methods. I might even advocate LiteratePrograming<a href="http://c2.com/cgi/wiki?edit=LiteratePrograming">?</a> as a possible part of <a href="ExtremeProgrammingForOne.html">ExtremeProgrammingForOne</a>, though I'm not expert enough to know whether it could work well. --<a href="http://c2.com/cgi/wiki?GarethMcCaughan">GarethMcCaughan</a>
<hr>
<p>
In one article [<a href="http://www.literateprogramming.com/knuthweb.pdf">http://www.literateprogramming.com/knuthweb.pdf</a>] (kudos to <a href="http://c2.com/cgi/wiki?TomLeylan">TomLeylan</a> for digging up this paper, initially quoted from memory) <a href="http://c2.com/cgi/wiki?DonaldKnuth">DonaldKnuth</a> mentions that he deliberately chose the name <a href="LiterateProgramming.html">LiterateProgramming</a> in reaction to the name <a href="http://c2.com/cgi/wiki?StructuredProgramming">StructuredProgramming</a> (which at the time was used, I believe, to hype the family to which <a href="http://c2.com/cgi/wiki?PascalLanguage">PascalLanguage</a> belongs).
<p>
He resented the slur implied in the <a href="http://c2.com/cgi/wiki?StructuredProgramming">StructuredProgramming</a> label : nobody, he said, would admit to writing an <em>unstructured</em> program. So in a one-up play, he came up with <a href="LiterateProgramming.html">LiterateProgramming</a> because nobody would admit to writing an <strong>illiterate</strong> program.
<p>
<hr>
Adding comments is not at all XP, but there are some other aspects which are:
<p>
Knuth's journal article on <a href="LiterateProgramming.html">LiterateProgramming</a> mentions that <em>the programmer should choose his variable names with a thesaurus in his hand</em>, not resting until he has found the name best reflecting its purpose and function (citing out of memory, oh boy). That certainly sounds like XP to me.
<p>
And writing an article means rewriting it until you like it -- which is a lot like refactoring.
<p>
--<a href="http://c2.com/cgi/wiki?ArieVanDeursen">ArieVanDeursen</a>
<hr>
<strong>This is the way Knuth has implemented <a href="LiterateProgramming.html">LiterateProgramming</a>.</strong> First, there is a source language, called WEB. Then, there are two tools, called TANGLE and WEAVE. TANGLE takes the WEB source and rearranges it for presentation to a Pascal compiler, stripping out the comments. WEAVE takes the WEB source and produces a TeX document with table of contents and index, that includes all the documentation, formatted beautifully, along with the code, which appears more or less as it was written in the WEB source.
<p>
There is also a more modern CWEB language which comes with CTANGLE and CWEAVE and produces C or C++ output instead of Pascal.
<p>
In source form, a CWEB (or WEB) program (or document) consists of named sections. Most of these sections are small and should contain a few lines of code. You can elevate some of them into chapter headings. CWEAVE numbers the sections and produces a table of contents (using the chapter headings) and an index.
<p>
CWEAVE formats the sections in the order you typed them, but CTANGLE can rearrange them according to your specifications. <em>The code in any section can &quot;include&quot; code from other sections without actually stating that code on the spot.</em> Think of each section as a long-named, parameterless, single-use macro which you can use before, or after, it is defined. This allows you to present the code in one order, while the compiler sees it in another. So there's no reason you can't produce &quot;chapter 1: overview,&quot; with actual code in it, and then produce &quot;chapter 2: the lexical analyzer.&quot; A reader can use the table of contents to skip the chapters that bore him in the woven TeX file. For the compiler, CTANGLE can embed the lexical analyzer in the middle of the overview.
<p>
I was intrigued by Literate Programming, but I found it difficult, because I had to debug not only the program but the documentation; sometimes it wouldn't format correctly and needed help. It's like having twice as much work to do. But the reordering was enough to inspire me to invent the <a href="http://c2.com/cgi/wiki?BuildSyntax">BuildSyntax</a>. --<a href="http://c2.com/cgi/wiki?EdwardKiser">EdwardKiser</a>
<p>
<hr>
<a href="http://c2.com/cgi/wiki?CategoryBook">CategoryBook</a> <a href="http://c2.com/cgi/wiki?CategoryTex">CategoryTex</a>
<hr>
<a href="http://c2.com/cgi/wiki?edit=LiterateProgramming">EditText</a> of this page (last edited February 16, 2001)<br>
<a href="http://c2.com/cgi/wiki?FindPage&value=LiterateProgramming">FindPage</a> by browsing or searching<p>
<font color=gray size=-1>This page mirrored in <a href="index.html">ExtremeProgrammingRoadmap</a> as of March 31, 2001</font>
</body>