The development cycle and literate programming

From:	Paolo Amoroso
Date:	25 May 1995

During software development, the output of the specification and design stages is often a series of documents containing text, diagrams, tables, formulas, etc. Since a literate programming system: supports the implementation stage, is able to integrate all the above mentioned documents, doesn't usually force a particular order of creation and allows their production by successive refinement, Is it wise to use such a system also in the first stages of development? In other words, how early in the program development cycle can literate programming tools be effectively employed? Any opinion - or account of direct experience - will be highly appreciated.

From:	Lee Wittenberg
Date:	25 May 1995

I think so -- right from the start. In fact, I think literate programming can be a logical extension of what Bertrand Meyer is talking about when he advocates using a programming language as a specification and design language as well. Once the specifications are set, code chunks can be added as necessary in the appropriate parts of the document. The code chunks will be close to the specification of the feature they implement, and therefore, can be more easily checked.

When I do literate programming, I frequently leave chunks open for future development. In fact, one of the projects I am working on is a design for a prototype system, in which the purpose of the code chunks is simply to illustrate roughly how things can be put together; I don't intend to actually tangle and compile the web. On the other hand, if the design seems workable, the web might very well form the basis for the actual prototype.

One of the advantages I have found with literate programming is that *It Doesn't Have To Be Publication Quality* (take note, Norman. What's important is that the thoughts get down on paper. Incompletely expressed thoughts are better than no thoughts at all. In my experience, it's much easier to check text chunks for accuracy than traditional comments, partly because of the different typography, but more, I suspect, because text chunks use complete sentences, while traditional comments usually don't. The discipline of writing a complete sentence tends to promote accuracy a bit more than that of writing sentence fragments. It may be, of course, simply that literate programmers are just better communicators than anyone else.

Even "semi-literate" programs, like the noweb source have advantages over traditional programs. *The Chunk Names Themselves Carry Information.* In particular, they show the programmer's thought processes with respect to design and stepwise refinement. Even though the noweb code is mostly unadorned code chunks (incompletely indexed), I have no compunction about browsing around the code, looking for information. The chunk name <<make all those damn active characters ``other''>> is a particular favorite of mine. My nocond macros make use of information gleaned this way to typeset conditional chunks interestingly, and to change the "(not defined)" and "Root chunk" messages to "(conditional)" and "Conditional chunk", respectively. It was significantly easier to find what I needed than it would have been in a straight-line LaTeX style file.

From:	Patrick McPhee
Date:	26 May 1995

Paolo Amoroso writes: [...] In other words, how early in the program development cycle can literate programming tools be effectively employed?

Wayne Sewell argued in favor of using literate programming tools to write specifications (in "Weaving a Program").

From:	Don Wallace
Date:	05 Jun 1995

I am fascinated by the title of this forum... Can anyone tell me, if practical, what the formal definition of literate programming is? I assume that literate programming has to do with the writing of source code, and alludes to construction of programs that are humanly readable as logical descriptions of processes. (True?) Does it also encompass such practices as commenting of code?

For what it's worth, I have been witness over the years to what one could only call 'illiterate programming'... cryptic variable names, non commented code, inexplicable spaghetti, all ignorantly defended by the idiot-savant programmer/propeller head/whining prima donna-with-an-attitude of the moment as being 'necessary' because 'we need to get this out.'

If the above hypothesis of what literate programming is, is correct, then I am (sadly) afraid that 95% of the slop that is written in the commercial world is truly <<illiterate>>... In fact most programmers I have known probably do not read more than the the back of the cereal box in the morning... while admirable, literate programming is swimming against the tide.