commons-lang/xdocs/developerguide.xml

177 lines
7.6 KiB
XML

<!--
Copyright 2002-2005 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.
-->
<document>
<properties>
<title>Developer guide for Jakarta Commons "Lang"</title>
</properties>
<body>
<section name='Developers guide for Jakarta Commons "Lang"'>
<div align="center">
<h1>The Jakarta Commons <em>Lang</em> Package</h1>
<h2>Developers Guide</h2>
$Id$<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 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>
<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 &lt;code&gt;&lt;/code&gt;.</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 &lt;code&gt;&lt;/code&gt;.</p>
<h4>Classes/Interfaces/Methods</h4>
<p>Use a short description of what the class/interface/method is used for,
enclose with &lt;p&gt;&lt;/p&gt;.</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 &lt;p&gt;&lt;/p&gt; 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 &lt;pre&gt;&lt;/pre&gt;.
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>Site Generation</h4>
<p>Site generation via maven includes Clover report generation. Since Clover
requires a license, the proper license file must be placed where the maven
Clover plugin can find it. This can be done as follows:
<ul>
<li>Obtain the license file (clover.license) from the committers svn repository (https://svn.apache.org/repos/private/committers/), in the donated-licenses path.</li>
<li>Copy clover.license to the lang base directory (the top level directory where project.xml, maven.xml, etc. reside).</li>
<li>Copy clover.license to your maven repository Clover licenses directory, named clover-[version].license, where [version] is the version specified in the
project.properties <b>maven.jar.clover</b> property. For example, if
<b>maven.jar.clover</b> is set to <b>1.3.2</b>, then the clover license file
name should be <b>clover-1.3.2.license</b>.</li>
</ul>
</p>
<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 &lt;junit&gt;
optional Ant task, rather than the more messy technique of invoking Java with
the &lt;java&gt; 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>