james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <acoli...@apache.org>
Subject Re: about javadocs (was: Re: FW: What do we need to release 2.1?)
Date Sun, 18 Aug 2002 17:58:57 GMT
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:vincent.keunen@manex.be]
>>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:james-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:james-dev-help@jakarta.apache.org>


Mime
View raw message