RE: Literate Programming (Was: Comments are KILLING me)
- To: mathgroup at smc.vnet.net
- Subject: [mg37803] RE: [mg37768] Literate Programming (Was: Comments are KILLING me)
- From: "David Park" <djmp at earthlink.net>
- Date: Wed, 13 Nov 2002 01:12:20 -0500 (EST)
- Sender: owner-wri-mathgroup at wolfram.com
The idea of literate programming is certainly worthwhile and I heartily endorse it. But there is a difference in emphasis between notebooks and packages. If a notebook is written for someone else to read then the object is to communicate in as clear a manner as possible and literate programming is the order of the day. Packages are generally meant to provide computational facilities and there literate programming is less important. Instead good documentation is more important. NOTEBOOKS 1) Use Text cells to explain what you are doing. The explanation is as important as the code. You can start a Text cell by putting the selection point between cells and typing Alt-7. Then start entering the text. Don't use Input cells, or group headers for comments. 2) Use graphics to illustrate points. You can put the graphics code in a closed cell when the code itself is not of interest. 3) Use Section and Subsection grouping with Automatic Grouping. Never use Manual Grouping. Don't present a reader with a long unstructured notebook. 4) If you are trying to instruct as to method, write code in steps instead of using highly nested one-liners. You can always wrap it up after the explanation. You can put multiple steps in one cell where the use of % is unambiguous. 5) Shy away from too much use of colored cells or text. This may be clear to you but it is seldom clear to the reader who does not know the color coding and is not going to spend a lot of time learning it. Good form is clear but not a spectacle. PACKAGES 1) If you want to make the package code and methods available to users use a package notebook. You can use grouping and Text cells just as before. Here I differ from Selwyn's advice. It is much easier to edit and change an organized package notebook than a long text file. And you can include all the text explanation you want. The grouping and text explanation disappear in the package.m file, but there is no reason the user should look at that anyway. He can look at the notebook. 2) It would be nice if Mathematica did not throw away delimited comments, (* *), when a cell is converted to InputForm or StandardForm. I think that is a design fault in Mathematica. Inline comments are useful because they point to specific pieces of code, something that is difficult to do from a preceding Text cell. 3) If you are ambitious, write documentation and individual Help pages with examples for each command. It is not really that difficult to do. The Help examples can also serve double duty as test notebooks. Unfortunately, most packages do not have good documentation. David Park djmp at earthlink.net http://home.earthlink.net/~djmp/ From: Nafod40 [mailto:may106 at psu.edu] To: mathgroup at smc.vnet.net Selwyn Hollis ... > Just a remark: > > Writing package code with a simple text editor can give you more > control, fewer headaches, and cleaner code faster. Ahhh, but that would completely remove my main purpose for using Mathematica. If I was to just write standard source code, I would do it in something far less quirky and much more in the mainstream than Mathematica. I'm trying to follow the Literate Programming paradigm, whereby the you intersperse code with your documentation, not the other way around. To quote it's originator, Donald Knuth (of TeX and "Art Of Programming" fame) from http://www.literateprogramming.com/ *************** Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99. I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming." Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other. ********************* Another great quote... Ross Williams. FunnelWeb Tutorial Manual, pg 4. A traditional computer program consists of a text file containing program code. Scattered in amongst the program code are comments which describe the various parts of the code. In literate programming the emphasis is reversed. Instead of writing code containing documentation, the literate programmer writes documentation containing code. No longer does the English commentary injected into a program have to be hidden in comment delimiters at the top of the file, or under procedure headings, or at the end of lines. Instead, it is wrenched into the daylight and made the main focus. The "program" then becomes primarily a document directed at humans, with the code being herded between "code delimiters" from where it can be extracted and shuffled out sideways to the language system by literate programming tools. The effect of this simple shift of emphasis can be so profound as to change one's whole approach to programming. Under the literate programming paradigm, the central activity of programming becomes that of conveying meaning to other intelligent beings rather than merely convincing the computer to behave in a particular way. It is the difference between performing and exposing a magic trick. ****************** Mathematica has the right balance of documentation and codability to fully support this paradigm if it would JUST WORK AS ADVERTISED.