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
