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 15:53:57 GMT
Vincent Keunen wrote:
> 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
>

I disagree. You wouldn't release Documentation with no code would you? 
Why would you release code with no documentation?  If documentation 
isn't a condition for release, you'll never do it.  So say what you mean
"Absolutely someone else...the mythical someone else..should document 
JAMES, but quality is not important to me so I'd rather get it out the 
door undocumented and hope the mythical someone else comes along"

> 
>> 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.
>>

retranslate:  "Code quality is not important"


> 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).
> 





--
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