138 lines
5.3 KiB
HTML
138 lines
5.3 KiB
HTML
<!--
|
|
Copyright 2002-2004 The Apache Software Foundation.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
<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.7 2004/02/18 23:13:37 ggregory 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>
|
|
<li>the class will not be final</li>
|
|
<li>for null parameters, rather than throwing an Exception, consider performing a Null patterned concept, such as returning 0 or ""</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>
|
|
|
|
<h4>Exception throwing</h4>
|
|
<p>When throwing an exception to indicate a bad argument, always try to throw
|
|
IllegalArgumentException, even if the argument was null. Do not throw
|
|
NullPointerException. (Obviously, you should document what the code actually does!)</p>
|
|
|
|
<h4>Deprecations</h4>
|
|
<p>When deprecating a method or class include a clear reference to when the method will be deleted.
|
|
This should be of the form 'Method will be removed in Commons Lang 3.0.'.
|
|
|
|
<h4>Language used in code/comments</h4>
|
|
<p>It has been decided to casually standardize on US-English.
|
|
To avoid misplaced jeers of 'americanisation', the people making this decision largely write in non-US-English.
|
|
However, it's not something to get worked up about.
|
|
Lots of spelling differences will creep in all over.</p>
|
|
|
|
</body>
|
|
</html>
|
|
|
|
|