Maintainability and Documentation (Was: Reply: A few modest proposals for maxima maintinability)

--- Richard Fateman <fateman@cs.berkeley.edu> wrote:
> Raymond Toy wrote:
> >James Amundson <amundson@fnal.gov> writes:
 
> >Greatly reduce the number of
> >conditionals (i.e., #+Multics) in the
> >code. Use the "port" package from CLOCC
> >whenever possible. Remove
> >support for PDP10, Multics, etc.
> >Reformat the code to consistent case
> >and indentation conventions,
> >without changing any of the logic.
> >Perform the case and indentation
> >stages in separate steps committed to
> >CVS.
> > 
> > I disagree with 2) and 3).  It's way 
> > to easy when doing these things
> > to say "Hey, this is ugly.  Let me just
> > like so."  And suddenly some weird case
> > breaks and no one knows where now because
> > EVERY single line has been touched.  It
> > ain't broke so don't fix it.

One possible concern I have is that if the code can't
stand fixing such as that, it might be hard to improve
and maintain it.  Wouldn't we want the code robust
enough to be able to handle minor cleanups?   For
example, suppose something is broken, someone writes a
fix for it, and although the fix itself is clean and
well written some quirk in the code renders it
unusable.  If the policy is to write the fix in such a
way that it doesn't break anything, rather than fix
the quirk, and that results in some messy code, that
just makes the overall system harder to maintain the
next time someone wants to do something.  Over enough
iterations  mightn't that cause real trouble?

Again these are just my thoughts and concerns.  I
don't know if it would work this way or not.  It seems
like a concern worth voicing, though...

> Just a thought...
> You may find that the best documentation for some
> features is
> exactly the stuff you want to remove.  That is, the
> multics or pdp10
> code which has the same functionality but in a
> different lisp may
> actually explain what the CL is trying to do!

That reminds me, here's another thought. Maybe we can
branch into two distinct efforts here - those of us
who are currently able to understand the maxima code
can make improvements and fixes as they like, and the
rest of us can start going through the last stable
release (5.6, I think?) and begin to do a big
documentation effort - user manuals, annotated
examples for all types of problems, general
introductions into the how and why of Lisp and Maxima,
detailed descriptions of how the guts of maxima work
and which files do what and how, etc.  It will force
us to figure out what's going on, keep us out of the
hair of those who know what's going on internally, and
be useful at the same time.  I know there are a few
documentation people out there - should we try to
organize ourselves and make a good stab at this?

Also, did we decide on any uses of the sourceforge
maxima site?  I kind of get the sense that maybe the
best thing to do for a while, at least, is keep the
development stuff where it is, and make the
sourceforge site into kind of a point of entry for
newcomers and maybe a place to do some documentation
efforts?  I hate to see the site go to waste, and
right now there isn't much on it.  Comments?

CY

__________________________________________________
Do You Yahoo!?
Get email alerts & NEW webcam video instant messaging with Yahoo! Messenger. http://im.yahoo.com