A few years ago I was given the source code for a very large lisp project (Axiom, a million+ lines of code). As one of the original developers I felt that it would be easy to maintain.
It is quite a humbling experience to review code 15-20 years after you wrote it. So much information is lost and what was perfectly clear at the time is now obscure and opaque. As a result of this experience it became clear to me that you need a deep change of philosophy about documentation and coding in general. Much more of the human aspects of the problem need to be captured and preserved if code is to live and be useful 30 years from now. Knuth attacked this problem years ago with his Web project. The basic ideas were that you "write for humans", not "code for machines". To do that you construct a "literate program", that is, a file that contains both documentation and data. The key insight of his idea is that you begin to write documents for humans rather than code for machines. It's very hard to make this mental transition but very necessary, at least in my opinion, for the long term survival of your program. Web uses 2 programs "tangle" which extracts pascal code and "weave" which extracts latex documentation. Tangle is too program specific for lisp so I switched to Norman Ramsey's "noweb" program which will accept any programming language. Axiom has been completely rewritten as literate programs. There are no lisp, C, Makefile, spad, aldor, include, etc. files. Everything is now a document and the Makefiles automatically extract the programs. My experience with this has been good so far and I've finally made the transition of writing for humans rather than machines. I can see the huge difference it makes when I open a "program" from last year and can easily understand and modify it. Inline documentation styles (;;;, ;;, ;) tend to be written with the assumption that you already understand the whole program so they tend to be terse and very context sensitive. "Internals document" styles are separate from the source code, never get close to reality, and are rarely maintained. Literate programs can overcome both of these issues provided you make the mental transition of writing for other humans rather than the machine. Consider using literate programs rather than homegrown tools. I believe you'll find that your programs will survive to reach the 30-year horizon. Tim Daly _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
