| <html> |
| <head> |
| <title>Developers guide for Jakarta Commons "Lang" Package</title> |
| <head> |
| <body bgcolor="white"> |
| |
| |
| <div align="center"> |
| <h1>The Jakarta Commons <em>Lang</em> Package</h1> |
| <h2>Developers Guide</h2> |
| $Id: DEVELOPERS-GUIDE.html,v 1.1 2002/12/22 21:07:35 scolebourne Exp $<br /> |
| <a href="#Introduction">[Introduction]</a> |
| <a href="#PackageStructure">[Package Structure]</a> |
| <a href="#UtilityClasses">[Utility Classes]</a> |
| <a href="#Javadoc">[Javadoc]</a> |
| <br /><br /> |
| </div> |
| |
| |
| <a name="Introduction"></a> |
| <h3>1. INTRODUCTION</h3> |
| |
| <p>The <em>Lang</em> package contains a set of Java classes that extend |
| the basic JDK classes. This developers guide seeks to set |
| out rules for the naming of classes and methods within the package. The purpose |
| of this, as with all naming standards, is to improve the coherency and |
| consistency of the whole API.</p> |
| |
| <p>The philosophy of the naming standards is to follow those of the JDK |
| if possible.</p> |
| |
| |
| |
| <a name="PackageStructure"></a> |
| <h3>2. PACKAGE STRUCTURE</h3> |
| |
| <p>The main package for Lang is <code>org.apache.commons.lang</code>. Subpackages should |
| be created for each group of related items. </p> |
| |
| <p>Each package should have a <code>package.html</code> file for javadoc. This should |
| describe the use of the package and its scope.</p> |
| |
| |
| |
| <a name="UtilityClasses"></a> |
| <h3>3. UTILITY CLASSES</h3> |
| |
| <p>Utility classes provide additional functionality around a class or interface. |
| Examples include StringUtils and SerializationUtils.</p> |
| |
| <p>Each class shall follow the naming pattern XxxUtils where Xxx relates to the |
| class or interface that the utility services. Variations on a theme (<code>Integer</code> |
| as opposed to <code>Number</code>) should be dealt with in one Utils class where possible. |
| Each Utils class shall:</p> |
| |
| <ul> |
| <li>be a single, static method based, class</li> |
| <li>have a name consisting of the interface name plus 'Utils'</li> |
| <li>deal with one class or interface and its variations (subclasses)</li> |
| <li>provide methods that perform useful utility functions</li> |
| </ul> |
| |
| <p>A utility class can act as a factory for specific implementations of a class or |
| interface. In such cases the implementations should be non-public, static, inner classes |
| of the utility class. However, if warranted due to maintenance or other reasons, these |
| decorator classes may be moved to top-level classes in a subpackage. The |
| naming of such a subpackage should be discussed and agreed upon on the |
| developers mailing list.</p> |
| |
| |
| |
| <a name="Javadoc"></a> |
| <h3>4. JAVADOC</h3> |
| |
| <p>The Sun javadoc guidelines are the starting point for Lang. These points are |
| an extension to make it easier for users reading the generated |
| docs and developers with javadoc-popup capabilities from within their IDE.</p> |
| |
| <h4>General</h4> |
| <p>References to other objects, interfaces or methods use the @link-tag the |
| first time it is referenced in a class or interface. On the following |
| references always enclose it inside <code></code>.</p> |
| |
| <p>References to <code>null</code>, <code>this</code>, <code>long</code>, |
| <code>int</code>, <code>short</code>, <code>char</code>, <code>byte</code>, |
| <code>double</code>, <code>float</code> and <code>boolean</code> should be enclosed |
| in <code></code>.</p> |
| |
| <h4>Classes/Interfaces/Methods</h4> |
| <p>Use a short description of what the class/interface/method is used for, |
| enclose with <p></p>.</p> |
| |
| <p>A longer description about what the class/interface/method is used for |
| and if it is needed how it is done. If it is nessesary include |
| description of the parameters, what they are used for and how. Enclose |
| with <p></p> where it is needed, try to divide into smaller parts (not |
| to small!) to enhance readability of the generated Javadoc.</p> |
| |
| <p>If an example is needed enclose it with <pre></pre>. |
| It should be supported with an explanation within a normal paragraph.</p> |
| |
| </body> |
| </html> |
| |
| |