2002-12-22 16:07:35 -05:00
|
|
|
<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>
|
2003-07-30 19:54:33 -04:00
|
|
|
$Id: DEVELOPERS-GUIDE.html,v 1.2 2003/07/30 23:54:33 bayard Exp $<br />
|
2002-12-22 16:07:35 -05:00
|
|
|
<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>
|
2003-07-30 19:54:33 -04:00
|
|
|
<li>the class will not be final</li>
|
2002-12-22 16:07:35 -05:00
|
|
|
</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>
|
|
|
|
|
|
|
|
|
|
|
