[Top][All Lists]

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

[Axiom-developer] documenting changes

From: root
Subject: [Axiom-developer] documenting changes
Date: Wed, 12 Jan 2005 15:48:00 -0500


I'm in the process of trying to merge the axiom--windows--1 branch
with the axiom--main--1 branch.

There are dozens of files with changes and no documentation.
It is painfully obvious that the message isn't getting out.

The point of the free and open source Axiom is documented code.
This project differs from all other projects in one main feature;
every file in the system is a tex document. There are no C, lisp,
boot, spad, Makefile, include files, etc. EVERYTHING is (or will be)
a DOCUMENT. You're not writing C code, you're writing a document.

The reason that Axiom is all documents is because *I* wrote portions
of Axiom many years ago and commented nothing. Now I'm looking at my
own code and, even though I tried to write dirt-simple, perfectly 
clear code, I no longer understand the "why" of it. The end result
is that Axiom is very hard to maintain and modify. As time permits
I'm going back and writing the documentation for the existing code.

If Axiom is going to be a living project we MUST change the way 
Axiom developers write and modify code. How else is someone, 30
years from now, supposed to understand and update your code?

So if you make a change to the source DOCUMENT you really do need to
write a paragraph that explains the need for the change and what was

If you don't write a paragraph to explain the change then I have to
reverse-engineer your change, write the documentation, and hand-merge
the results.

As a result the axiom--windows--1 merge is going VERY slowly. There
are undocumented changes to the algebra, to the interpreter, and to
the library code.

If you made changes to the axiom--windows--1 branch please revisit
the changes and send me patches that contain documentation; not just
comments, real words about why the change was needed. Write for the
future maintainers.

Believe me, I know that it is painful to have to write documentation.
But without it Axiom will surely die. Please take the time.


reply via email to

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