[math] Proposed initial content for Guidelines in developer.xml

[Phil Steitz <ph...@steitz.com>]

Here is a draft that I was preparing to submit as a patch to 
developer.xml; but given that some of the content may be controversial, 
I thought it best to post to the list first for discussion.  This is 
just a start.  I just wanted to get something out there to build on. I 
will submit as a patch if there are no major objections.

<section name='Guidelines'>
  <p>
    Developers are asked to comply with the following development
    guidelines. Code that does not comply with the guidelines including
    the word <i>must</i> will not be committed.  Our aim will be to fix
    all of the exceptions to the "<i>should</i>" guidelines prior to a
    release.
  </p>
    <subsection name='Coding Style'>
     <p>
      Commons-math follows <a href="http://java.sun.com/docs/codeconv/">
      Code Conventions for the Java Programming Language</a>. As part of
      the maven build process, style checking is performed using the
      checkStyle plugin, using the properties specified in
      <code>checkStyle.properties</code>.
      Committed code <i>should</i> generate no checkStyle errors.
     </p>
    </subsection>
    <subsection name='Documentation'>
     <ul>
      <li>
       Committed code <i>must</i> include full javadoc.</li>
      <li>
       All component contracts <i>must</i> be fully specified in the
       javadoc class,interface or method comments, including
       specification of acceptable ranges of values, exceptions or
       special return values.</li>
      <li>
       References to definitions for all mathematical
       terms used in component documentation <i>must</i> be provided,
       preferably as HTML links.</li>
      <li>
       Implementations <i>should</i> use standard algorithms and
       references to algorithm descriptions <i>should</i> be provided,
       preferably as HTML links.</li>
     </ul>
    </subsection>
    <subsection name='Unit Tests'>
     <ul>
      <li>
       Committed code <i>must</i> include unit tests.</li>
      <li>
       Unit tests <i>should</i> provide full path coverage. </li>
      <li>
       Unit tests <i>should</i> 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. </li>
     </ul>
    </subsection>
   </section>

Phil


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