[Maxima-commits] [git] Maxima CAS branch, master, updated. branch-5_31-base-204-g29fe517

>>>>> "Rupert" == Rupert Swarbrick <rswarbrick at gmail.com> writes:

    Rupert> Raymond Toy <toy.raymond at gmail.com> writes:
    >> I haven't been following your changes very closely, but I was wondering why
    >> the seemingly gratuitous renaming of PTERM to PTTERM?  Does PTTERM make
    >> more sense in some way?

    Rupert> The idea is that "PT" means polynomial terms. The convention is
    Rupert> something like:

    Rupert>   - PFOO   expects a polynomial.
    Rupert>   - PTFOO  expects the terms of a polynomial (the CDR of a polynomial)
    Rupert>   - CFOO   treats its argument as a coefficient (either because it's a
    Rupert>            number (PCOEFP is true) or because it's a polynomial in a
    Rupert>            later variable than the one we're thinking about at the
    Rupert>            moment. 
    Rupert>   - PCFOO  Takes a polynomial and a coefficient

    Rupert> etc. etc. The "C" and "PC" conventions already existed.

Ah, that seems nicer.  Perhaps a short comment documenting this
convention will be helpful?

    >> Also, I know it's hard, but is it possible to separate the documentation
    >> phase from the changes phase?  Some of your commits say you're adding
    >> documentation, but then lots of code is changed.  Perhaps only indentation
    >> changed, but still, someone might look at it and wonder. :-)

    Rupert> Yeah, I agree, but some of the "documentation" effort is rewriting the
    Rupert> code to use post-1970 control structures and avoid so many side
    Rupert> effects. The idea is that the code never changes meaning, but it may be
    Rupert> far far easier to understand afterwards. For example, I'm busily trying
    Rupert> to get my head around PTIMES1 at the moment, which has a do loop
    Rupert> containing a prog form with six(!) labels.

    Rupert> Maybe I'm using the wrong verb when I say "document" - what would you
    Rupert> suggest?

That's why I said it's hard.  Maybe if you say "document", but also
note that you're changing the code.  I just read one of the commits
and I think the log said it was documenting the code.  And then
further on I saw that lots of code also changed.  

My personal preference is that if you figured it, document it.  Then
change it.  Or if you change it first, commit the change and the
documentation at the same time.

Git has no problem with too many commits. :-) It's the gigantic single
commits that are burden on the user and future git bisects.

Ray