style and conventions



On Monday 11 August 2008 07:36:20 pm Robert Dodier wrote:
> On 8/11/08, John Lapeyre <pdl at johnlapeyre.com> wrote:
> > I am writing some Maxima code that I will clean up and
> >  release. It is for quantum information, so I think it is
> >  best distributed as a third party package.

> My advice is to make it look like some existing Maxima code.
> Here are some exemplars:
>
> share/contrib/log10.mac
> share/contrib/amatrix/amatrix.mac
> share/contrib/augmented_lagrangian.mac

I already made, and am using log2.mac, which is nothing more
than search and replacing in log10.mac. Then I tried to
model simplifying conjugates on log10.mac, but that turned
out not to be a good approach. I'll look at the others.

> Common features: header comments; ample white space;
> pronounceable identifier names; right parentheses stuck
> together (not hanging).

I really like hanging parens with indentation so that I know
at a glance what closes what. I assume there is a good
counter-argument from lisp.

> Also please consider creating a test script (a collection of
> pairs of expressions, one is an input and the other is the
> expected output). batch(rtest_foo, test) runs a test script
> named rtest_foo.mac.

I already have been making test scripts as I go along, with
handrolled routines for counting success.  Its no problem to
convert them to the format in the contrib directories.

> Aliases lead to pain & suffering.

Well regardless, after looking more at the code, I think would not be too
useful.

> If the code is all Maxima code, it should be straightforward to
> apply the namespace stuff. If you want to send me a version
  
Ok, I'll post a link to a web page.

Also there is the question of documentation. I messed with
texinfo and got something to kind of compile with errors. I
wonder if files external to the package need to be edited
and databases rebuilt.


  Thanks for the help,
  John