didier,
I looked at the link, read the code, and read the documentation.
Kudos to David. He's documenting his code. And he's using what
I'd characterize as a semi-literate style. I'd fit him into a
scale that looks something like:
Illiterate:
0) raw code
1) raw code with minor comments
2) raw code with organized comments
Semi-literate:
3) code with extractable comments (aka javadoc, doxygen)
4) code with latex comments (dsbweb)
Literate:
5) documentation with embedded code (web)
His comment style is exceptionally good. He writes for human readers.
My only nitpick comes from the fact that he's "still the programmer"
writing for the machine and decorating his code with nice comments.
It is better than no comments at all but I don't think he really
became fully literate. For the kind of "little-file, C-mindset"
programming he is doing it probably isn't worth it. Literate
programming and the "file" idea tend to get in the way of each
other. {C, Java, etc} programmers tend to be unable to transcend
the file-based thinking.
The hardest thing I found about making the transition to literate
programming is that the "literate" part overrides the "programming"
part in importance. That is, besides writing for humans in comment
style you also end up having to "scramble" the program so it takes
on a logical development style for the human reader. Writing for
the human is much harder and more time consuming than writing for
the machine. It only makes sense if the program is intended to
be maintained by other humans over a long time, raising the need
to write for humans.
dbsweb is clearly a "comment processor tool", like javadoc. The
structure of the program overrides the comment structure. Thus, "main"
ends up being the last thing in the file because the machine needs it
that way. But if you read things like "Lisp in Small Pieces" he
starts out explaining things "top-down", so he starts explaining the
"main" program first. dbsweb doesn't have chunking and thus does not
allow you to "float" things into a logical sequence for the human. You
are primarily talking to the machine and dragging the human along.
That said, I'm happy to see that he has "gotten the idea" well enough
that he's willing to build a tool to help him along. But he still
hasn't raised his eyes from the machine.
Thanks for the link.
Tim