Sheldon Newhouse wrote:
> Hello,
> 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.
>
Based on commit messages, the number is probably closer to 10, perhaps
fewer.
> 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."
This is always a dilemma. Those who can fix bugs and enhance things
want to do that, not write documentation. Those who like to write
documentation can't understand the code.
All that can be reasonably expected is that people write comments on
tricky parts of the code. I try to do this, but sometimes it's
"obvious" (but not really); sometimes, I don't really understand; and
sometimes, I'm just plain too lazy. And sometimes the checkin comment
explains it, unfortunately.
Ray