james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Vincent Keunen <vincent.keu...@manex.be>
Subject about javadocs (was: Re: FW: What do we need to release 2.1?)
Date Sun, 18 Aug 2002 14:12:58 GMT
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


> 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

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message