📄 literateprogramming.html
字号:
<head><title>Literate Programming</title></head><body><h1><img src="logo.gif"> Literate Programming</h1><a href="LiterateProgramming.html">LiterateProgramming</a> <a href="http://www.amazon.com/exec/obidos/ISBN=0937073806/portlandpatternrA/">ISBN 0937073806</a> is a book by <a href="http://c2.com/cgi/wiki?DonaldKnuth">DonaldKnuth</a>, published in 1992. The errata can be found at Knuth's web site at <a href="http://www-cs-faculty.stanford.edu/~knuth/lp.html">http://www-cs-faculty.stanford.edu/~knuth/lp.html</a>
<p>Before the book, Knuth presented his ideas in an article titled <em>Literate Programming</em> in <em>The Computer Journal</em>, <strong>27</strong>(2):97-111, 1984.
<hr>
Literate Programming is a programming methodology that
combines a programming language with a documentation language.
<p>From one source you can produce both the documentation and
the executable code. A good example of what can be done
with this methodology can be seen in the book <a href="http://c2.com/cgi/wiki?TexTheProgram">TexTheProgram</a>.
<p>Literate Programming is also the name of the book which
describes the methodology.
-- <a href="http://c2.com/cgi/wiki?ToddCoram">ToddCoram</a>
<hr>
I believe Knuth's original goal also included printed output.
(Certainly all the fine work on TeX and derivatives would
argue that point!) Is this component of literate programming
becoming obsolete?
<p>Certainly, Knuth's philosophy includes a <em>linearizing</em>
theme, an assumption that code and documentation are
both interleaved and sequential. The Nelsonian system you are
using to read this message is non-sequential, and it contains
no code. Would merely adding a <em>programming language</em> to this
<em>documentation language</em> produce "literate programming?"
<p>I think it is time to move beyond literate programming, while
acknowledging its wonderful contribution. I think programming
documentation should embody:
<OL><li> <strong>Conceptual integrity:</strong> the documentation for a <em>thing</em> must be on the same conceptual level as that thing.
<li> <strong>Constant accuracy:</strong> the documentation for a <em>thing</em> must constantly and accurately describe that thing.
<li> <strong>Accessibility:</strong> the documentation for a <em>thing</em> must be accessible, by creators, their peers, re-users, reviewers, end-user documentors, and the merely curious.
<li> <strong>Measurability:</strong> the documentation for a <em>thing</em> must be measurable, quantitatively and especially qualitatively.
</OL>Literate programming, as conceived by Knuth, wonderfully addressed 1 and 2, but left much to be desired with 3 and 4.
<p>Hypermedia holds the promise of addressing 3, which Barbara and I have expanded in some detail and implemented in Smalltalk.[<a href="http://www.bytesmiths.com/pubs/9506ManagingDocs.html">http://www.bytesmiths.com/pubs/9506ManagingDocs.html</a>]
Although our solution is original, it is hardly unique -- there is lots of discussion about
<em>hyper-literate programming</em> these days.
<p>But the remaining problem is number 4; we can measure the quantity of documentation, but that is often <em>inversely</em> proportional to its quality!
<p>Getting back to the site topic, I think there may be hope in applying patterns to measuring the quality of documentation. Ideas?
-- <a href="http://c2.com/cgi/wiki?JanSteinman">JanSteinman</a>
<hr>
CWeb doesn't have to be inaccessable or on paper. It's been recently extended to output PDF, and will probably generate HTML sometime. The PDF output contains hyperlinks, bookmarks, etc. I've recently been reading
<a href="http://www.literateprogramming.com/adventure.pdf">http://www.literateprogramming.com/adventure.pdf</a>, a CWeb'ed translation of the original Adventure. -- AlanSHutko
<hr>
I remind readers that this site is itself written as a literate program in an extended version of itself called <a href="http://c2.com/cgi/wiki?HyperPerl">HyperPerl</a>. I believe this implementation completely satisfies Jan's Accessibility requirement. I'll also point out that nobody has yet used the wiki features of <a href="http://c2.com/cgi/wiki?HyperPerl">HyperPerl</a> to contribute a bug fix or extension. -- <a href="http://c2.com/cgi/wiki?WardCunningham">WardCunningham</a>
<UL><li> <a href="http://c2.com/cgi/wikibase">http://c2.com/cgi/wikibase</a>
<p></UL>(1) Thanks for pointing this out. Nice approach.
(2) Why would anyone modify a program with that sort of licence?
--<a href="http://c2.com/cgi/wiki?AndyGlew">AndyGlew</a>
<hr>
Thank you for saying, "Knuth's philosophy includes a linearizing theme, an assumption that code and documentation are both interleaved and sequential. The Nelsonian system you are using to read this message is non-sequential, and it contains no code."
<p>The linearizing aspect of Knuth's examples of literate programming have always bother the heck out of me. I felt he had just written the program where the default was comment without delimiters (i.e. most just changed the syntax for the compiler). I have seen other systems, particularly IBM's FAPL executable specification language for SNA, which also produced both readable documents and compilable code. Also linear.
<p>I feel that in literate programming, the problem and its should be described in the manner best suited to the problem and the intended readership. That means non-linear, in a compiler's sense. Fragments of procedures presented out of order, procedures presented in any order, data structures introduced in any order. Perhaps objects give us a handle on the non-linearization, because they can be created in any order, and methods are very short. Webbed descriptions could also be fine, but of course people do read one sentence at a time, and when you convert to paper there is an order to the paper. But that order should be ordered to the reader, not the compiler (until it is time to compile)!
<p><a href="http://c2.com/cgi/wiki?AlistairCockburn">AlistairCockburn</a>
<hr>
I think people are misunderstanding ordering in Knuth's <a href="LiterateProgramming.html">LiterateProgramming</a>; it says that you write the program in the order it makes sense as a story. Knuth's premise is that the programmer should not be constrained by the order that the compiler expects, since this is typically not the order that we think in. A Web file is treated as orderless; all expressions are evaluated simultaneously. This means that usage of a function (or anything) can occur before any declaration. I am no expert, but I have written a few CWeb-like programs (although not in the original CWeb or Pascal). I have also written a few JavaWeb<a href="http://c2.com/cgi/wiki?edit=JavaWeb">?</a> programs, and the Web preprocessor (for lack of better terminology) makes an excellent adjunct to the preprocessor-less Java world.
<p>-JasonNordwick<a href="http://c2.com/cgi/wiki?edit=JasonNordwick">?</a>
<p>As Knuth has emphasized, the real philosophy behind literate programming is that programs should <strong>not</strong> be written primarily for computers. The primary purpose of a a computer program is to <strong>explain itself to its readers</strong> (including the author).
<p>Literate programming tools allow code to be written and read in a human-friendly format, and later transformed into a computer-friendly format. In this sense, literate programming is another step along the path from machine code to assembly languages to higher-level languages.
<p><hr>
"But that order should be ordered to the reader..." This is exactly the responsibility of the author. The author of a literate program is a storyteller, making sense, as do all good stories, of the complex, mysterious, and frightening.
<p>I don't take my kids to the deep dark woods and tell them, "Just wander around and see what you find," I tell them stories. A literate programmer should do the same. It is as if, for the reader, the storyteller is sitting right there saying, "Let me tell you about the program."
<DL><dt> <dd><em>When I take my kids to the woods, I also tell them to just wander around. Kids are really <a href="http://c2.com/cgi/wiki?GoodAtLookingAround">GoodAtLookingAround</a>. -- <a href="http://c2.com/cgi/wiki?JimCoplien">JimCoplien</a></em>
</DL>This is not easy to do. As the writer you have to make assumptions about your audience- what questions they will be asking and in which order and what will constitute a good explanation.
<p>Because writing literate programs is hard to do, and because you will have different kinds of readers, sometimes you will miss the mark. That's no reason to completely abdicate your responsibility to your readers, even if that abdication is wrapped in the techno-pacifier of <a href="http://c2.com/cgi/wiki?HyperText">HyperText</a>.
--<a href="KentBeck.html">KentBeck</a>
<hr>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -