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 14:36:21 GMT
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.

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


Mime
View raw message