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

[Tim Daly]

> 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. 

Martin,

Given my mono-maniacal focus on documentation I think I may have
mis-read what you wrote. Let me try another interpretation.

Are you asking "How do I modify existing code?". For new algebra that
I've written I've tried to provide documentation. But for existing
algebra I've been VERY relucant to change things, even where there
seems to be a better way. Fixing mistakes and extending the code
seem reasonable but changing the existing API?

One key reason is "backward compatibility". The book and the test
cases document the language and algebra. Old code should continue to
work, otherwise we get into the "python 2.7 vs 3.3 debates". If the
old code doesn't work the system is, by definition, broken.

Old code always has warts. Common Lisp has CAR which could easily
have been subsumed and removed by extending the definition of FIRST.
Pretty, but ... yeah, broken by definition.

Another key reason is that the author of the code was likely an expert
in the area. Even experts make mistakes that need to be fixed but
wholesale rewrites seem rather drastic. A rewrite assumes a higher
level of expertise. Some of the Axiom code was written as PhD thesis
work so the bar is pretty high.

That said, there may be valid reasons to modify or rewrite algebra.

> 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.

Unless there is some overarching reason it is hard to see the need to
rewrite existing code. A new design that regularizes many domains
might make a good reason. A complete extension of the whole area, such
as a major matrix package might make DHMATRIX a useless subset. But
changing the API of an existing domain so that old code doesn't work
is, by definition, broken.

Mistakes in the code will occur both in old code and in new code.
Unfortunately new mistakes are only likely to be uncovered by new
people using the new code... which by recursion on the motivation
to rewrite the code...  leads to yet a different set of mistakes. 

Code doesn't rust. It doesn't "get old". Especially computational
mathematics code. Tearing down the cathedral because we now know
how to make stones that lasts longer seems ... I don't know ...
disrespectful of the genius of the original architects?

Tim