Re: [Axiom-developer] Must hear...

[u1204]

> So what should one do if one wants to modify parts of Axiom (or its 
> forks) where all there is is the code?
> 
> Should one:
> 1) Trace through the code and try to reverse engineer the documentation, 
> then modify that.
> 2) Try to understand generally what it does (such as working out what 
> the inputs and outputs are). Then rewrite it from scratch in a 
> documentation led way.
> 
> For me, in a lot of cases, I would prefer option 2. I would not claim to 
> be as smart as the original authors, any algorithm that I would come up 
> with might be less efficient and inferior in many respects. However I 
> would try to document it as well as I could and try to make it a better 
> basis for future improvement. Also, if I am going to make mistakes, at 
> least I would learn more from my own mistakes.

For existing code there are many ways to approach the problem and I
can't recommend any general approach. The main goal to keep in mind is
to speak to a broad audience who might need to do something with the
code. For instance, with the sequence prediction code, what is the idea?
What papers should be read? What subset of the problem is covered? Are
there boundary cases?  Are there examples to try? How is the code
structured? Does it depend on a limit package? Does it work over floats?

The approach I'm taking is to start from the code, find the related
theory, then understand and document from the theory to the code.
At that point I feel I know enough to critically examine the code.

Any algebra author sufficiently clever and educated to write an algebra
package (e.g. JET), is bringing a LOT of background to the code. Writing
reasonable documentation without their help is a formidable challenge.
However if Axiom is going to survive and surpass the current state of
the art it is necessary to try.

If the information is available it can easily be restructured into the
books, hyperdoc, help files, ++ comments, test files, and examples.

The new )describe command currently shows working examples. That can be
enough for someone to start using the domains. The new )help command
will (eventually) pop into a browser worksheet with a series of
worked-out problems, explanations, and a live connection to the
interpreter so experiements can be done.

New algebra authors really do need to spend the time and effort to
bring the quality of their documentation up to the quality of their
code. Writing down the ideas while writing the code is not particularly
challenging and, in fact, is very likely to improve the quality of the
code, based on feedback from those who tried.

As Roboert Persig said in "Zen and the Art of Motorcycle Maintenance", 
it's all about quality. As Knuth said, it's all about communication.
Stealing from both, I say it is all about quality communication.

Tim