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

[Phil Steitz]

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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]