On Wed, 2002-11-20 at 14:05, Benoit Grégoire wrote: > 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?
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. 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. 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.... -- Matthew Vanecek <[EMAIL PROTECTED]>
signature_asc_DEFANGED-22340.DEFANGED-27198
Description: application/defanged-27198
