Thanks Peter, for your message that makes things move forward. I'm adding some comments about the specific item of javadocs. First, I must say that I agree with 2 comments from Noel:
> Internal Documentation > Absolutely necessary. But NOT to hold up the 2.1 release. We can continue > to upgrade the web site with new documentation, and any serious developer > should be working from the CVS and > At least get the javadoc complete. > > javadocs are for developers. I view 2.1 as a RELEASE build for users. Yes, > we need to work on the javadocs, but I would not wait for them before > putting out a stable release build if we can do so. > Peter M. Goldstein wrote: >Internal Documentation > >I know some people tend to dismiss internal documentation, but I don't >see how a project that is seeking to attract developers can function >without it. As such I tend to include it in the exit criteria for a >particular release. > >1) All methods and instance variables should be documented. All classes >should be documented. The documentation doesn't need to be extensive, >but it should be present. It should include issues such as class/method >contracts and threading restrictions where appropriate. >2) All public and protected classes, methods, and variables need to be >documented using Javadoc style to ensure appropriate Javadoc >3) The Javadoc should build without warnings >4) All packages should have package documentation > > > Peter, I'd like to modify a bit your suggestion. From my experience (15 years of OO software developement), doc should be reduced to the minimum (and I find XP discussions about documenting the code quite appropriate to modern developments). Some ideas: * code is the only thing that really lives; it changes often (writing docs is time consuming and is very difficult to keep in sync with the code; and out of sync doc is useless, and may even lead you to wrong assumptions...) * the code (at the class/method level) should be self explicit: if you need doc to explain code, think about rewriting code to make it more explicit; also, good developers read code almost as easily as the doc (if the code is good, of course) * doc is very useful at the package level: "what does this package contain, where to look first" (important classes and methods should be mentionned) * important classes/methods may need some doc * important here meaning "part of an API, important for external developers" or "part of the basic building blocks of the system, that all developers should be comfortable with" I really don't want to start a lengthy discussion on the pros and cons of documentation (see the forum related to that), but I believe that docs should not get in the way of developing fast (especially on a volunteer basis, with restrained resources). And I am convinced that it won't hurt the project's perennity... Just my 2 cents (and I hope I did not offense you, Peter). -- !try; do() -- Vincent Keunen, Ir, http://vincent.keunen.net Manex, rue Wagner 93, BE-4100 Boncelles, Belgium Our site: http://www.manex.be