Re: [Axiom-developer] Nice Fixes! Another go on IssueTracker

[root]

>I know that documentation is one of the most important things for the 
>Axiom project, but your approach to fixing bugs is just strange.

My approach to code development in Axiom is strange. But I'm fighting
against the "get it done" crowd and trying to go for "get it right"
and "get it documented".




>Suppose you have software A which has very few documentation and it has 
>a bug B.
>
>You can produce from that two systems A1 and A2.
>
>A1: Fix the bug today. Fix the documentation in 1 year.
>A2: Fix the bug together with the documentation in 1 year.
>A3: Fix the bug today. Fix or don't fix the documention.


A4: Fix the program. Which, in Axiom, means fix the literate
    document, which implies fixing the documentation as well
    as the code.





>Clearly, in the long term A2 is the best, but actually A1 is better 
>since it contains a partial fix of the code tomorrow.

That is the kind of short-term thinking that I'm trying to avoid.  You
are optimizing ("the best") the wrong function.  Every developer I
know worries about "tomorrow" and doesn't care about next month. 

If you take a 30-year horizon view, the answer to the question about
"what is best" changes. It is no longer vital that the change happen
quickly. It is vital that the change is correct and that the function
is documented well enough so that anyone can see that the change is
correct. Achieving "the best" is a good thing, but you have to know
what you are trying to optimize for it to make sense. As a
mathematician I know you understand this.

Axiom is trying to optimize for the next generation. Thus a bug
fix is "good" but a documented function which is clearly corrected
by this bug fix is "best". After all, it might turn out that the
bug exists in a function that shouldn't exist at all, or in a
function that is poorly defined, or in a function that could be
decomposed into several more general functions, etc.. Unless you
lift your eyes away from your desk you won't see the larger, longer
term picture.





>Now what about A3?
>
>Software A does not have enough documentation. So in some way A3 is as 
>worse as A. But A3 is better since it has fewer bugs.

Axiom will always have bugs. And the known bugs won't disappear off
the bug list. However, a "quick fix" to a non-critical bug means that
no-one will ever look at the problem again. If you know enough to fix
it you know enough to document the block of code containing the bug.

In non-algebra code I'm going a bit further. When I change things now
I "tree shake" the code, pick it up, add it to the proper book volume
along with all supporting code, and document the functions.

In algebra code I'm generally trying to understand the function well
enough to find good documentation sources since no-one who is actually
a domain expert seems to care enough to document. When I do write new
algebra code (e.g. the Exponential Integral E1 function I just added)
I find sources and write documentation.




>
>I know that every bugfix introduces new bugs, but since A3 fixes a known 
>bug and passes all tests, it only might introduce a new yet unknown bug.
>And one should not forget... there are many eyes at the mailing list 
>watching what happens to the code. Some people might even be able to say 
>something about a possible (yet unknown) bug.

Well, my eyes are the "eyes of last resort" and I'm pretty careful 
about changing things, especially algebra code I don't understand.
Since Axiom code runs in many different domains a "simple" fix that
works for integers might be wrong for finite fields. We don't have
peer-reviewed literature for bug fixes. The algebra code was written
by experts in their respective domains and I really look critically
at bugs that "work for me" without proper understanding.





>
>Just some thoughts that don't count ...

When I'm doing bug fixing I need to understand that code that is 
being fixed. Since I need to understand the code I can clearly
explain at least the parts I understand. Given the huge amount
of code in Axiom it is likely that the buggy code is going to
be visited just once. If there is no explanation added at the
time I'm debugging, there will be no explanation later. All that
will remain will be a small code change with no explanation.

Take, for instance, bug 370. There the original bug fix was to
change the algebra code from (something like)

  f(a+b)

to 

  c:=a+b
  f(c)

When I went to apply this patch it didn't look right. But there
was no documentation about what the patch was intended to do.
It eventually turned out that the correct patch was to fix the
spad compiler.



The long term goal of Axiom is to be understandable and maintainable
by developers we've never met. If I can't understand why a change is
being made now due to lack of documentation why would I expect that
someone 30 years from now will understand it? If it is minimally
documented now so that I can understand it, then there is some hope
that future developers can also understand it.

When changing an algebra function there is an implicit assumption
that the developer has a fair amount of domain knowledge, not generally
shared by all of the developers. Given that you understand a function
it is not unreasonable to ask that the fix at least explain a little
bit about the function, either why it was wrong or how it works now.





After 36 years of programming I know that nobody is going to sit
down and "document" all of Axiom. It has to be done incrementally
both because the task is too large and because no one person has
all of the expertise.

The people who worked on Axiom are dying off. One of the original
group members died Friday and I'm going to the funeral tomorrow.
We need to make the code live longer than the developers.

Tim