[Axiom-developer] On literate programming (or the use of noweb)

[David MENTRE]

Hello,

I have recently used literate programming and more specifically
noweb. I'd like to share my experience, from a software engineering
point of view. If you find this boring, just skip this email.

I have used noweb on:

 - a network processing program in C

 - a client/server in Objective Caml (with some XDR (C-like syntax))

 - a formal model in Promela (for Spin verifier)


I use deliberately a very restricted form of chunk inclusion. Basically:

 Explanation on f1...                        (1)
<<my_file.lisp>>=
(defun f1 ...)
@

 Explanation on f2...
<<my_file.lisp>>=
(defun f2 ...)
@

 Explanation on the complicated algo using f1 and f2...
<<my_file.lisp>>=
(f1 () (f2 ...))
@

It is just concatenation of various code chunks in a file. 

In fact, I find the other use of noweb chunks:

<<my chunk>>=                                (2)
(defun f...)
@

<<my_file.lisp>>=
(map ... <<my chunk>> ...)
@

...*very* dangerous. It is just a simple text expansion as would do a C
#define. You lose, for example, all the good properties of Lisp macro
definition with macro parameters renaming.


I also try to stick as much as possible to the programming language that
I am using. For example, OCaml uses text scope for parameters
definition, so I avoid using noweb chunks to define functions in
different order. Each file in the original language as its counterpart
as noweb file. 

One issue I have done on the literate C program was that all the modules
of the C program were in the same noweb source file. After some times,
it was a total mess.

Of course, each rule has its exceptions. For example, Promela hasn't any
capabilities to define functions, so I have used noweb chunks to define
some kind of macro.


To conclude, I would advise the following rules for the use of noweb
into the Axiom project:

 1. avoid as much as possible the definition of code chunk which are
    _included_ in other chunks. Prefer concatenation of code chunks. In
    short, prefer form (1) over (2);

 2. restrict yourself to the capabilities of your language. For example,
    define and use Lisp macros and not noweb chunks as lisp macros.


What is your opinion?


I hope it brings something to the general issue of software design and
coding.

Yours,
d.
-- 
David MENTRE <address@hidden> -- http://www.nongnu.org/axiom/