noweb and Lisp
gratefulfrog
I'm not sure how much interest there is in this topic, but I have
recently created some add-ons to NOWEB that enable it to better handle
Common Lisp code.
These are all available, with instructions, at my website:
http://gratefulfrog.net
Cheers!
GF
Roland Kaufmann
Hello GF,
your noweb add-on for Lisp looks interesting, thanks for making it
available.
What is your experience combining interactive Languages like Lisp with
Literate Programming? I found it difficult to avoid the tendency to
add code interactively, bypassing noweb, so the webs tended to be code
with little annotation added.
regards
Roland
Joe Riel
I've used it for writing elisp programs (emacs modes). Yes, it takes
a bit of discipline to avoid directly adding code to the untangled
file, however,the literate program output (hyperlinked pdf) is easier
to follow, compared to an equivalent .el file, when I have to return
to the code a few months later.
Given that elisp programs generally consist of lots of fairly small
functions, I use chunks mainly to group the functions rather than
to decompose them.
Joe
gratefulfrog
LaTeX and then running scripts to get the code out before loading it
into the Lisp envt. But I am quite disciplined. In fact, I look at
literate programming like writing literature more than writing
programs. I try to tell a story and the code is only one part of the
story. The execution of the code is another part.
I sometimes debug in the tangled source and sometimes in the original
LaTeX, it depends on what I'm trying to accomplish. In any case, only
the original LaTeX is delivered. That rule ensures that I always
maintain the literate version, only.
I am also a very heavy commenter. Before becoming a literate convert, I
found my source code with code-line/comment-line ratios of 1/10 or
more, so Literate programming was a natural step.
I believe that if you have to read the code to understand the program,
then the program will soon be replaced.
Hope this helped.
Cheers,
GF.
Roland Kaufmann
GF> I personally have no problem writing the program and the
GF> explanation in LaTeX and then running scripts to get the code
GF> out before loading it into the Lisp envt.
That is what I did when using LP with programming languages such as
C[++], where this is just an extra rule in the makefile and does not
change the workflow.
GF> But I am quite disciplined. In fact, I look at literate
GF> programming like writing literature more than writing
GF> programs. I try to tell a story and the code is only one part
GF> of the story. The execution of the code is another part.
This is what I tried as well, though my webs are probably more like
car maintenance manuals (this is Norman's metaphor, IIRC) than
stories.
With interactive languages such as Matlab/Octave or Lisp, I am tempted
to exeriment interactively and annotate a transcript afterwards.
GF> I sometimes debug in the tangled source and sometimes in the
GF> original LaTeX, it depends on what I'm trying to accomplish.
GF> In any case, only the original LaTeX is delivered. That rule
GF> ensures that I always maintain the literate version, only.
Of course. I had a problem once where gdb was confused because I had
reused a chunk and there was no one-to-one correspondence between the
lines in the .nw and .c files, but that was easily rectified.
GF> I am also a very heavy commenter. Before becoming a literate
GF> convert, I found my source code with code-line/comment-line
GF> ratios of 1/10 or more, so Literate programming was a natural
GF> step.
This is how I came to LP myself. For an alternative point of view,
see Rob Pike's style notes, e.g.
http://www.lysator.liu.se/c/pikestyle.html
"Avoid cute typography in comments, avoid big blocks of comments
except perhaps before vital sections like the declaration of the
central data structure (comments on data are usually much more helpful
than on algorithms); basically, avoid comments. If your code needs a
comment to be understood, it would be better to rewrite it so it's
easier to understand."
And in the Plan 9 operating system, you can see examples:
http://plan9.bell-labs.com/sources/plan9/sys/src/
GF> I believe that if you have to read the code to understand the
GF> program, then the program will soon be replaced.
While I agree that programs should be understandable, I am afraid that
many (most?) programs do not satisfy your condition, but are unlikely
to be replaced...
GF> Hope this helped.
Yes, thank you.
regards
Roland
gratefulfrog
> to be replaced...
I don't agree. In my career as researcher, programmer, architect,
project leader, manager, clown, etc., I find that programs are always
being extended, i.e. partially replaced, to increase functionality.
I was often called upond to save ship-wrecked software, particularly a
100,000 line C++ project. I found that the simple rule of thumb was
that if we couldn't understand a method in 5 minutes, then we should
delete it and see if the program worked any better without. If it
didn't we re-wrote the code properly, guessing at the original
intention. Programs got shorter as functionality increased. This is
also what happens when you use Paul Graham style 2-phased devt. (cf.
http://www.paulgraham.com/).
Indeed, the problem with reading code is that the intention of the code
is not explicitly manifest. It is the knowledge of this intention which
is needed to understand a program.
Cheers,
GF
Sven Utcke
> GF> I am also a very heavy commenter. Before becoming a literate
> GF> convert, I found my source code with code-line/comment-line
> GF> ratios of 1/10 or more, so Literate programming was a natural
> GF> step.
>
> This is how I came to LP myself. For an alternative point of view,
> see Rob Pike's style notes, e.g.
> http://www.lysator.liu.se/c/pikestyle.html
>
> "Avoid cute typography in comments, avoid big blocks of comments
> except perhaps before vital sections like the declaration of the
> central data structure (comments on data are usually much more helpful
> than on algorithms); basically, avoid comments. If your code needs a
> comment to be understood, it would be better to rewrite it so it's
> easier to understand."
I couldn't disagree more: Of course I can always see what the code is
doing --- the problemis that without proper commenting I have no way
of knowing whether the code does what the last programmer thought it
ought to do...
Sven
--
_ __ The Cognitive Systems Group
| |/ /___ __ _ ___ University of Hamburg
| ' </ _ \/ _` (_-< phone: +49 (0)40 42883-2576 Vogt-Koelln-Strasse 30
|_|\_\___/\__, /__/ fax : +49 (0)40 42883-2572 D-22527 Hamburg
|___/ http://kogs-www.informatik.uni-hamburg.de/~utcke