Today is my rant day ;) Here are some comments and suggestions about developer documentation in GnuCash. As a fairly new (8 months) GnuCash hacker, I think I have an good perspective on this. Perhaps some of the following isn't true. If so, the mere fact that I haven't noticed by now is proof enough that it is far from obvious. Currently, the barrier to entry for GnuCash is very high, even if new developers are greeted with patience and open arms. The problems include:
1-Gnucash is simply huge. Here are some useless but interesting statistics about the size of the codebase (Physical source line of code, excluding comments and whitespace): ansic: 207 585 (78.57%) scheme: 32 731 (12.39%) 2-The gnucash design info pages, which are the primary developper documentation, are no longer kept up to date. 3-Module documentation is incomplete. How to create a new module, insert it in the build system and get gnucash to load it not documented. 4-Several important scheme functions are completely undocumented. (Are ANY scheme functions documented?) 5-There needs to be a FAQ on how to add new GUI elements: preference pages, menu entry, etc. 6-The GnuCash codebase is very scarcely commented. Solutions: 1-Not much we can do about this. There is some code duplication, but you can only go so far. Flagging unimplemented or non-functional header files or functions would be a good thing however. 2-I don't think we have the human ressources to keep this updated in it's current form, now that no one is payed to work on GnuCash. One solution would be to move this documentation into the source or header files and use a tool like doxygen (http://www.stack.nl/~dimitri/doxygen/) to generate the doc. It would certainly help with keeping the documentation updated. But we need a tool that will work with Scheme. 3-Update the module documentation. And at least create "dummy" modules (one in scheme, one in C) to serve as code example. Perhaps that would be documentation enough. 4-Since scheme doesn't have header files, we need a solution like 2 5-We need to write it and keep it updated, especially since the APIs for this moved a lot recently. 6-I presume that this comes from a time when Gnucash was developed intensively by a tight group of people, relying on complete and up to date design documents. I know some people consider that the code should speak for itself and comments are a distraction. But someone coming into a new project can't be expected to know every function name, and to such a person, ANY code is hard to understand without general comments about what a section of code or a non trivial function call is expected to do. Obviously we can't go back an comment the entire codebase, but I think this should be remembered by all hackers for new or modified code. Obviously all this is a huge amount of work, but would help attract casual hackers that will then become addicted... Agreeing on what should be done would be a good start. I think 2 and 3 should be the priority. Comments? -- Benoit Gr�goire http://step.polymtl.ca/~bock/ _______________________________________________ gnucash-devel mailing list [EMAIL PROTECTED] http://www.gnucash.org/cgi-bin/mailman/listinfo/gnucash-devel
