Developers Guide Robert Burrell Donkin

Creating and maintaining a mathematical and statistical library that is accurate requires a greater degree of communication than might be the case for other components. It is important that developers follow guidelines laid down by the community to ensure that the code they create can be successfully maintained by others.

Developers are asked to comply with the following development guidelines. Code that does not comply with the guidelines including the word must will not be committed. Our aim will be to fix all of the exceptions to the "should" guidelines prior to a release.

Commons-math follows Code Conventions for the Java Programming Language. As part of the maven build process, style checking is performed using the checkStyle plugin, using the properties specified in checkStyle.properties. Committed code should generate no checkStyle errors.

  • Committed code must include full javadoc.
  • All component contracts must be fully specified in the javadoc class, interface or method comments, including specification of acceptable ranges of values, exceptions or special return values.
  • References to definitions for all mathematical terms used in component documentation must be provided, preferably as HTML links.
  • Implementations should use standard algorithms and references to algorithm descriptions should be provided, preferably as HTML links.
  • Committed code must include unit tests.
  • Unit tests should provide full path coverage.
  • Unit tests should verify all boundary conditions specified in interface contracts, including verification that exceptions are thrown or special values (e.g. Double.NaN, Double.Infinity) are returned as expected.
  • All new source file submissions must include the Apache Software License in a comment that begins the file
  • All contributions must comply with the terms of the Apache Contributor License Agreement (CLA)
  • Patches must be accompanied by a clear reference to a "source" - if code has been "ported" from another language, clearly state the source of the original implementation. If the "expression" of a given algorithm is derivative, please note the original source (textbook, paper, etc.).
  • References to source materials covered by restrictive proprietary licenses should be avoided.

Here is a list of relevant materials. Much of the discussion surrounding the development of this component will refer to the various sources listed below, and frequently the Javadoc for a particular class or interface will link to a definition contained in these documents.

Concerning floating point arithmetic.
http://www.validlab.com/goldberg/paper.ps
http://www.cs.berkeley.edu/~wkahan/ieee754status/ieee754.ps
Numerical analysis
Numerical Recipes (NR)
Scientific Computing FAQ @ Mathcom
Bibliography of accuracy and stability of numerical algorithms
SUNY Stony Brook numerical methods page
SIAM Journal of Numerical Analysis Online
Probability and statistics
Statlib at CMU
NIST Engineering Statistics Handbook
Online Introductory Statistics (David W. Stockburger)
Probablility and Statistics Resources
Online Journal of Statistical Software
References for mathematical definitions.
http://rd11.web.cern.ch/RD11/rkb/titleA.html
http://mathworld.wolfram.com/
http://www.itl.nist.gov/div898/handbook
Chan, T. F. and J. G. Lewis 1979, Communications of the ACM, vol. 22 no. 9, pp. 526-531.
http://www.wikipedia.org/wiki/