GnuCash developper documentation

[Matthew Vanecek]

--=-4csww0dr5GxtGZ0IoIwt
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On Wed, 2002-11-20 at 14:05, Benoit Gr=E9goire wrote:
> Solutions:
>=20
> 1-Not much we can do about this.  There is some code duplication, but you=
 can=20
> only go so far.  Flagging unimplemented or non-functional header files or=
=20
> functions would be a good thing however.
> 2-I don't think we have the human ressources to keep this updated in it's=
=20
> current form, now that no one is payed to work on GnuCash.  One solution=
=20
> would be to move this documentation into the source or header files and u=
se a=20
> tool like doxygen (http://www.stack.nl/~dimitri/doxygen/) to generate the=
=20
> doc.  It would certainly help with keeping the documentation updated.  Bu=
t we=20
> need a tool that will work with Scheme.
> 3-Update the module documentation.  And at least create "dummy" modules (=
one=20
> in scheme, one in C) to serve as code example.  Perhaps that would be=20
> documentation enough.=20
> 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=20
> moved a lot recently.
> 6-I presume that this comes from a time when Gnucash was developed intens=
ively=20
> by a tight group of people, relying on complete and up to date design=20
> documents.  I know some people consider that the code should speak for it=
self=20
> and comments are a distraction.  But someone coming into a new project ca=
n't=20
> be expected to know every function name, and to such a person, ANY code i=
s=20
> hard to understand without general comments about what a section of code =
or a=20
> non trivial function call is expected to do.   Obviously we can't go back=
 an=20
> comment the entire codebase, but I think this should be remembered by all=
=20
> hackers for new or modified code.
>=20
> Obviously all this is a huge amount of work, but would help attract casua=
l=20
> hackers that will then become addicted...  Agreeing on what should be don=
e=20
> would be a good start.  I think 2 and 3 should be the priority.
>=20
> Comments?

I whole-heartedly agree.  There are several great tools for creating API
references (e.g., javadoc, doxygen, etc).  My suggestion is to decide on
which tool would be best, and to create a standards doc. with comment
structure the #1 item in it.  As code is worked, the developer should
make an effort to put the comments into the standard format such that
the document tool can pick them out.  I think a mass update of
*everything* probably is very difficult to engineer.  All new
code/patches should be checked for properness before being committed.=20
It may also be a good time to standardize on a coding style to (e.g, GNU
vs K&R).  indent works wonders for massaging code into a single style...

I really like Benoit's suggestion of moving documentation to
header/source comments, because it's much more likely to be kept
up-to-date there, than if it were a separately maintained entity.=20
Design docs should also be stored in CVS, if possible and/or available.

I also agree with Benoit's assessment of starting work on a brand new
project.  The code *doesn't* always speak for itself, and in a very
large project, it often helps (a very very lot) to have a higher level
current design doc and API reference.  It would certainly help WRT
getting to work on the project--less time spent on tracing execution
paths means more time writing code (or drinking beer!!).

Other benefits too numerous to mention, no detriments that I can think
of...

Perhaps javadoc-format could be used in Scheme files, and be a
standard?  It would be good to have one tool for everything.

My $.02 US....
--=20
Matthew Vanecek <mevanecek@yahoo.com>

--=-4csww0dr5GxtGZ0IoIwt
Content-Type: application/DEFANGED-22340; name="signature_asc.DEFANGED-22340"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQA93su8OMmiB1jXEBsRAiIQAKCF1Luczn4OHumqzHD4NqhqDLWUhwCeN+uc
hB9uU9RzKvwlQmEnpQHuBK8=
=5A9J
-----END PGP SIGNATURE-----

--=-4csww0dr5GxtGZ0IoIwt--