166 lines
6.9 KiB
XML
166 lines
6.9 KiB
XML
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You 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.
|
|
-->
|
|
<document>
|
|
<properties>
|
|
<title>Developer guide for Commons "Lang"</title>
|
|
</properties>
|
|
<body>
|
|
|
|
<!-- $Id$ -->
|
|
|
|
<section name='Developer guide for Commons "Lang"'>
|
|
|
|
|
|
<div align="center">
|
|
<h1>The Commons <em>Lang</em> Package</h1>
|
|
<h2>Developers Guide</h2>
|
|
<br />
|
|
<a href="#Introduction">[Introduction]</a>
|
|
<a href="#PackageStructure">[Package Structure]</a>
|
|
<a href="#UtilityClasses">[Utility Classes]</a>
|
|
<a href="#Javadoc">[Javadoc]</a>
|
|
<a href="#Building">[Building]</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 developer 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>
|
|
|
|
<p>If different overloaded variants of a method are desired, with the same method signature, it should not be indicated via a boolean argument, but via a more focused method name. Rather than replace(boolean repeat), replace and replaceAll, or replaceOnce and replace. </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 necessary 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.'. </p>
|
|
|
|
<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>
|
|
|
|
<a name="Building"></a>
|
|
<h3>5.BUILDING</h3>
|
|
<h4>Building a Release</h4>
|
|
<p>
|
|
Commons Lang is intented to interoperate with Java version 1.2 and higher. To
|
|
achieve this, the distribution must be built with JDK 1.2. Why? Over time the
|
|
base JDK has changed. Building with JDK 1.4 would make some things in Commons
|
|
Lang not run with prior libraries. For example, new StringBuffer(StringBuffer)
|
|
was added after JDK1.2, but compiling under 1.4 could link to it. Run the code
|
|
under 1.2 and you get a NoSuchMethodError.
|
|
</p>
|
|
<p>
|
|
To build a release, the distribution should be build with Ant using JDK 1.2.
|
|
The Ant target <b>dist-build</b> in build.xml can be used to do this. The
|
|
site can be build with Maven.
|
|
<br/><br/>
|
|
Ant 1.6 or higher is required for building the distribution due to the way the
|
|
build.xml script invokes test cases. It uses the more modern <junit>
|
|
optional Ant task, rather than the more messy technique of invoking Java with
|
|
the <java> tag to run the test runner. For this to work, junit.jar must
|
|
be copied to the Ant home library directory.
|
|
</p>
|
|
</section>
|
|
</body>
|
|
</document>
|