Vincent,
I'm not offended, although I disagree almost entirely with your points. :) Basically I feel that on distributed, volunteer projects extensive and appropriate documentation is even more important than on projects being done by a full-time, localized development team. And I feel that it is extremely important even in the latter case. While XP is an interesting methodology, James is in no way an XP project. We are using none of the XP techniques (pair programming, rapid rotation of developers to different parts of the code base, aggressive refactoring of unclear code etc.) that make internal documentation far less important. And as observation of the changelog indicates, leaving javadoc out vs. adding javadoc has not made the development any faster. I believe that one of the essential things an open source project must do is attract developers. You do that by making the projects interesting, and the code easy to understand. To me, that means internal documentation. That's what allows a new developer to come up to speed in a very short time and participate productively in the project. And on this point at least the Apache code standards seem to agree with me. :) I also suggested that the internal documentation be tied to a release because: i) That way it actually gets done ii) When the release announcement spurs a few developers to take a look at the code base, they'll find a well-documented, inviting code base. I'd be happy to continue this discussion offline, but I stand by my original wish list entry. --Peter > -----Original Message----- > From: Vincent Keunen [mailto:[EMAIL PROTECTED]] > Sent: Sunday, August 18, 2002 7:13 AM > To: James Developers List > Subject: about javadocs (was: Re: FW: What do we need to release 2.1?) > > 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 -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
