GnuCash developper documentation
Benoit Grégoire
bock@step.polymtl.ca
Wed, 20 Nov 2002 15:05:29 -0500
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/