commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Phil Steitz" <p...@steitz.com>
Subject Re: [math][patch] Lets try this again, here's a new patch for Rolling
Date Thu, 15 May 2003 21:34:47 GMT
Phil Steitz wrote:
> robert burrell donkin wrote:
> 
>> On Thursday, May 15, 2003, at 05:34 AM, Mohan Kishore wrote:
>>
>>> Not that I know sqat about this level of mathematics, but I would 
>>> strongly
>>> recommend detailed JavaDoc of the algorithm, OR, a link to 
>>> whitepaper/article
>>> online which details the same. Failing which, I fear, the use/future
>>> development/debugging will surely suffer...
>>
>>
>>
>> +1
>>
>> i think that this will need doing before math could be released and 
>> it's probably easier to start as we mean to go on. 
> 
> 
> Agreed.
> 
>> it'll be easier to insist that future developers document their code 
>> properly (which is important since it'll be very difficult for 
>> committers to verify or debug algorithms without a precise definition 
>> of what they are supposed to do) if we all do this from the start. 
>> it'll also help avoid any possible problems with international 
>> differences in technical terminology.
>>
>> i'd say that the interfaces are probably the right place to document 
>> the mathematical operation being offered whereas the implementation 
>> should detail the aims of the implementation (eg memory footprint 
>> verses speed, small data sets verses large data sets, simple verses 
>> complex).
>>
> I agree here too. This is another reason that we might want to just 
> enforce a rule that all interfaces will be abstracted.  Refactoring as 
> we speak...
> 
>> maybe we could come up with a standard format for the class comments.
> 
> 
> I am struggling a bit on this. Here are some questions:
> 
> 1. I think it would be best to reference external documentation for all
>    definitions and standard computational formulas.  This obviously
>    creates dependencies and the need to maintain links.  Is this
>    OK?  Here is a good reference for basic stat definitions:
>    http://rd11.web.cern.ch/RD11/rkb/titleA.html.  If this is acceptable,
>    I will include references to the definitions there throughout.  We
>    will need to find similar sources for documentation of numerical
>    algorithms.
> 
> 2. The math/stat packages that I like the most (S-Plus, SAS) maintain
>    Users' and Programmers' Guides with detailed information on
>    algorithms and implementation details.  I am not sure that putting
>    all of the implementation documentation in the javadoc will be
>    convenient either for the developers or the users.  I would suggest
>    the following principles:
> 
>       * favor standard algorithms with external documentation and
>         document these using external references wherever possible
>       * document simple extensions/implementation notes in javadoc
>       * maintain a separate user's guide including more extensive
>         implementation notes, performance analysis, etc.
> 
> 3. In many (most?) cases it will be most convenient to define the
>    interface contracts and whatever implementation notes go in the
>    javadocs in the method comments rather than the class
>    comments
> 
> I will submit a simple example defining a chi-square test statistic 
> using these ideas in a message to follow.
> 

http://issues.apache.org/bugzilla/show_bug.cgi?id=19971

> Phil
> 
>>
>> - robert
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>>
> 
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> 




---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message