[Maxima] documentation of source?
ferriste at gmail.com
Sat Sep 5 03:13:48 CDT 2009
I fully agree with your comments. Maxima is a great software and in
its field I think it has no equal in open source. But on the other
side, what a potential new developer (or even a user) can see is that
the development process maybe is not the best, especially on the
documentation of source code.
I'm aware that, when Maxima becam open source, developers have
inherited a set of source files that are in a lot of parts cryptic and
uncommented from the beginning. For example I remember a discussion on
the mailing list related to source files of assume database, that are
uncommented and mostly incomprehensible, being so already 35 years
ago. This surely brings to great difficulties for developers.
I cannot disagree with who recently said on the mailing list that
Maxima sources are an "unfriendly place"... I'm only a user who knows
pretty nothing about lisp and surely my knowledge of mathematics is
poor, but I think that even a skilled programmer and matematician
would have some difficulties getting involved in development looking
at source files.
On the website is written that Maxima is currently in a transitional
state. This means that most of the development process is spent in
bugfixing and code improving. Why not use this transitional time to
try to let sources become more documented and understandable also for
potential developers? Surely from this will benefit both future (but
even actual) developers, and users that will have available a great
piece of software.
Another thing: a mailing list is surely a nice way to discuss about a
program if developers are few people, as for Maxima. But, in my
opinion, if this method will last for too much time, development
process wil became messy, especially if the number of developers will
increase. Maybe it could be useful writing down a simple roadmap, or a
todo list, on the website for example. Also a document explaining how
all function are implemented could surely be useful, and maybe this
could be the start.
I think that what pointed out by Sheldon Newhouse is important. Sooner
or later, this work about source documentation should be done.
Speaking as a user, I would appreciate if there were no newer releases
of Maxima even for a long time, if this time is spent in source
documentation. This will really help the future of Maxima, and this is
what one should try yo do in this transitional time.
I'm aware that this requires a lot of time, and that some sources are
a mess from the moment they were released under the GPL. And I'm aware
that developers are working hard to make Maxima even better, mostly in
their free time. But Maxima will became better if one think to its
long term development. This is really important.
2009/9/5 Sheldon Newhouse <sen1 at math.msu.edu>:
> I have some ideas that I invite comments on.
> 1. I don't know how many developers of maxima there are at present. From
> the mailing list I expect that there not more than 20 or 30.
> 2. I don't know the ages of the various developers, but if one wants to
> insure continued development for the long term, it is important to bring
> in young people and get them started on the development.
> This involves a lot of expertise, of course-lisp, tcl-tk,
> mathematical knowledge, etc. Obviously, different parts of the package
> depend on very different kinds of expertise.
> 3. Even with the required expertise, one does not want to re-invent the
> wheel. Some of the source files are very complex, and it takes
> considerable time for even expert programmers to understand them.
> Of course, some people have already spent much time understanding and
> improving certain parts of the program.
> In addition to making continued improvement, bug-fixes, etc., I think
> it is important to set up some way to train new people to come in and
> help with the development.
> So, this is a suggestion that people take some time away from
> development to document the files which already exist. The
> documentation could even be in the source files themselves.
> One standard answer is: "Ok, please feel free to contribute to this.
> It will be appreciated."
> This is certainly one reasonable answer from busy people. But I think
> it is much like asking others to spend the same amount of time on this
> or that project, maybe more, than people have already done.
> It is a recipe for slow development.
> It would be much healthier for developers so inclined to add descriptive
> comments on routines "as they do the development."
> Perhaps I am biased, but in my profession (university teaching and
> research), we are forced to do this in explaining various things to a
> new crop of people on a regulat basis. Sometimes it is painful,
> sometimes boring, but the benefits certainly appear when even a few of
> the recipients of the effort extend and improve the current status of
> Comments ?
> Maxima mailing list
> Maxima at math.utexas.edu
More information about the Maxima