[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: David MENTRE
Subject: [Axiom-developer] On literate programming (or the use of noweb)
Date: Tue, 14 Oct 2003 19:22:33 +0200
User-agent: Gnus/5.1002 (Gnus v5.10.2) Emacs/21.2 (gnu/linux)


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)
(defun f1 ...)

 Explanation on f2...
(defun f2 ...)

 Explanation on the complicated algo using f1 and f2...
(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...)

(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

David MENTRE <address@hidden> --

reply via email to

[Prev in Thread] Current Thread [Next in Thread]