Archive-Date: Tue, 22 Dec 1992 14:56:59 CST Date: Tue, 22 Dec 92 14:56:45 -0600 From: plyon@emx.cc.utexas.edu (Paul Lyon) Reply-To: LitProg@SHSU.edu Message-ID: <9212222056.AA00970@emx.cc.utexas.edu> To: LitProg@SHSU.edu Subject: OO Literate Programming? ---------------------------------------------------------------- On the face of it, it would seem that the concept of literate programming is not easily adapted to the "Object Oriented" approach to programming. Let us recur to Knuth's original article on the subject (I refer to the version reprinted in {\it Literate Programming}, CLSI, Stanford, 1992, pages 99--136). There we find literate programming characterized in a way that seems to fit best with the approach Knuth took in writing TeX and Metafont. The woven web file, when printed, is to read rather like a technical article (shorter programme) or a technical book (for example, {\it Metafont: the Program}). All of the source goes into one file, from which Weave will generate a section headings, a table of contents, a proper index for identifiers (and other things designated by the author using the Web control code), and an alphabetized listing of the code section names. The author is meant to follow a narrative order in presenting the parts of the programme; as Knuth says ``but always it is an order that makes sense on expository grounds'' (op cit, page 125). And further, "...there's no need to be hung up on the question of top-down versus bottom-up---since a programmer can now view a large program as a web, to be explored in a psychologically correct order..." (op cit, page 126). [I expect that, in most cases, there will be a number of ways of ordering that will work.] Finally, besides the obvious benefits to the reader---either another or oneself at some remove---of a more pleasing presentation of the source and of greater clarity, another benefit claimed, one now to the author, is a shorter time required to make the code work properly. The reason for this, according to Knuth, is that in preparing a proper account of the programme while writing it, one is led to clarify one's thoughts about it; as he puts it, you go into "expository mode". In trying to write enough to explain it to someone else, you are forced to explain it to yourself! [Aside: this last, in particular, is one of the things that I most liked about Knuth's idea when I first encountered it. The more carefully I write, the better I understand what I am writing about.] Now I have said this much about the original idea for two reasons: (1) it is an attractive idea about how to write programmes, and (2), more importantly, most of the existing Web systems are designed with this idea in mind. In particular, those features of WEB itself, and its progeny, Cweb, Fweb, Spiderweb, and so on, that go beyond the bare bones required for tangling and weaving, are mostly about forming the index, allowing the programmer to insert things besides identifiers in the index, forming the section headings, and the like, whence my remarks above about these matters. On the other hand, for "Object Oriented" programming, one is meant to split up a programme into a number of modules, most of which contain the interface and implementation for a single data type, or group of closely related data types, and only a few of which will contain the code that ties all of these together. Furthermore, the modules that contain the programme data types are meant to be relatively independent of the particularities of the programme one is working on. In pursuit of code reuse, one is meant to make something more akin to library code out of these, free-standing and comprehensible by itself rather than tightly integrated into one programme. It is this last that prevents one from simply adapting Cweb or Fweb in their current versions by using the file inclusion capability. This might work for the traditional way of laying out the modules that is used, for example, in C programming, but the approach taken in C++ programming is another matter. It is instructive, I think, to consider the contrast as given by Bjarne Stroustrup in Chapter 4 ("Functions and Files") of {\it The C++ Programming Language} (Second Edition, but the same is to be found in the first edition). The example Stroustrup gives is a simple calculator programme, rather like the one the Cameron Smith dug out of Kernighan & Ritchie and used for his Cweb example (described in previous postings to this group, and available from niord.shsu.edu). Stroustrup considers how this example, might be put in modular form in the traditional C style, and then goes to do describe a different layout of the kind one would use in C++ or Ada (and Modula 2, as well, I suspect). One gets five pieces: one contains the main programme, and the other four, each with its own header file and source file, contain (1) the error handler, (2) the symbol table code, (3) the eval code for the calculator, and (4) the lexical scanning code. All this, mind you, without yet introducing classes and inheritance; it is, rather, the prelude to that. Still, the header (interface) file contains the declarations of the data structure(s), if any, together with the prototypes of the functions that provide the services that are collected in this module, and the source file contains the implementation of those functions. Add in the real apparatus of C++ and one gets a header file with the class declaration(s) and a source file with the implementation of the class "methods". The syntax and accoutrement will be different for Eiffel, or Clos, or Ada, but the style remains the same. The obvious way to proceed is to construct a web source file from which you will generate the header file and implementation source, one that usually starts out with a description of the data type, with, perhaps, a table or itemized list giving brief descriptions of the methods (functions, procedures) for the data type, and perhaps, also one describing the fields of the data structure, and then goes on to string together the implementation of the functions, adding to each some account of its implementation where that is pertinent. In short, something that looks rather less like an exercise in literate programming as conceived by Knuth, and rather more like a UN*X man page with added source code. Now there may be no cure for this, or it may be that I am not imaginative in the right sort of way :-) In any case there is little in the way of support in the existing Web systems for this sort of thing So far as Weave goes, I have nothing concrete to suggest at this point, rather, I hope to stimulate discussion, assuming, as I do, that the efforts to add C++ support to Cweb mean that there are others out there with similar concerns. (I have the same thing, though, on my "Web wish list" as I suspect others do as well, namely support for user configurable pretty-printing styles; my tastes in these matters being significantly different from those of the authors of Cweb). Some things that come to mind for a C++ tangle, however, might include the following. First of all, most of us still have to contend with ``dumb'' linkers that insist on linking in the whole of a object module, even if one only uses a couple of things out of it. So it is desirable that one have a separate output file for each function or procedure defined in one of this library like modules, and further desirable that on each run of tangle, in the development phase I mean, one should generate only those output files that have changed since the last time one ran tangle. Otherwise, assuming that you already have a makefile for it least this much, you will end up recompiling the lot instead of just the one or two bits that you changed. [Funnelweb has a simple version of this; one of the reasons why I like it.] Indeed, it would be nice if tangle could generate the appropriate parts of the makefile for you (more to the point, the GNU makefile, since this will be the more easily done, I think, using GNU make). It would also be helpful if a C++ tangle would, given the definition of a function, generate a function prototype for you if you have not already provided one. This ``feature'' will not be simple one, since tangle will have to know where to put the prototype, and that will depend on whether the function is a class method, or a friend function, or one that just happens to live in the source file in question because it is more or less related to the class(es) being defined. On the otherhand, it could be a useful one; both in saving effort, and helping to cut down on programme errors. There are other things for the wish list as well, but I have likely said more than enough already :-) Comments, please? Ciao, Paul Lyon ----------------------------------------------------------------