Well said Peter. If your on Advogoto I'd love to upgrade you. -Andy
PS... very offtopic Furthermore de-emphasizing documentation is one of my key beefs with XP. While I hate 300 page specs, I hate 0 page ones too. Peter M. Goldstein wrote: > 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]>
