1<!-- 2Licensed to the Apache Software Foundation (ASF) under one or more 3contributor license agreements. See the NOTICE file distributed with 4this work for additional information regarding copyright ownership. 5The ASF licenses this file to You under the Apache License, Version 2.0 6(the "License"); you may not use this file except in compliance with 7the License. You may obtain a copy of the License at 8 9 http://www.apache.org/licenses/LICENSE-2.0 10 11Unless required by applicable law or agreed to in writing, software 12distributed under the License is distributed on an "AS IS" BASIS, 13WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14See the License for the specific language governing permissions and 15limitations under the License. 16--> 17<document> 18<properties> 19<title>Developer guide for Commons "Lang"</title> 20</properties> 21<body> 22 23 24<section name='Developer guide for Commons "Lang"'> 25 26<h1>The Commons <em>Lang</em> Package</h1> 27<h2>Developers Guide</h2> 28<br /> 29<a href="#Introduction">[Introduction]</a> 30<a href="#PackageStructure">[Package Structure]</a> 31<a href="#UtilityClasses">[Utility Classes]</a> 32<a href="#Javadoc">[Javadoc]</a> 33<a href="#Building">[Building]</a> 34<br /><br /> 35 36<a name="Introduction"></a> 37<h3>1. INTRODUCTION</h3> 38 39<p>The <em>Lang</em> package contains a set of Java classes that extend 40the basic JDK classes. This developer guide seeks to set 41out rules for the naming of classes and methods within the package. The purpose 42of this, as with all naming standards, is to improve the coherency and 43consistency of the whole API.</p> 44 45<p>The philosophy of the naming standards is to follow those of the JDK 46if possible.</p> 47 48 49 50<a name="PackageStructure"></a> 51<h3>2. PACKAGE STRUCTURE</h3> 52 53<p>The main package for Lang is <code>org.apache.commons.lang3</code>. Subpackages should 54be created for each group of related items. </p> 55 56<p>Each package should have a <code>package.html</code> file for javadoc. This should 57describe the use of the package and its scope.</p> 58 59 60 61<a name="UtilityClasses"></a> 62<h3>3. UTILITY CLASSES</h3> 63 64<p>Utility classes provide additional functionality around a class or interface. 65Examples include StringUtils and SerializationUtils.</p> 66 67<p>Each class shall follow the naming pattern XxxUtils where Xxx relates to the 68class or interface that the utility services. Variations on a theme (<code>Integer</code> 69as opposed to <code>Number</code>) should be dealt with in one Utils class where possible. 70Each Utils class shall:</p> 71 72<ul> 73<li>be a single, static method based, class</li> 74<li>have a name consisting of the interface name plus 'Utils'</li> 75<li>deal with one class or interface and its variations (subclasses)</li> 76<li>provide methods that perform useful utility functions</li> 77<li>the class will not be final</li> 78<li>for null parameters, rather than throwing an Exception, consider performing a Null patterned concept, such as returning 0 or ""</li> 79</ul> 80 81<p>A utility class can act as a factory for specific implementations of a class or 82interface. In such cases the implementations should be non-public, static, inner classes 83of the utility class. However, if warranted due to maintenance or other reasons, these 84decorator classes may be moved to top-level classes in a subpackage. The 85naming of such a subpackage should be discussed and agreed upon on the 86developers mailing list.</p> 87 88<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> 89 90 91<a name="Javadoc"></a> 92<h3>4. JAVADOC</h3> 93 94<p>The Sun javadoc guidelines are the starting point for Lang. These points are 95an extension to make it easier for users reading the generated 96docs and developers with javadoc-popup capabilities from within their IDE.</p> 97 98<h4>General</h4> 99<p>References to other objects, interfaces or methods use the @link-tag the 100first time it is referenced in a class or interface. On the following 101references always enclose it inside <code></code>.</p> 102 103<p>References to <code>null</code>, <code>this</code>, <code>long</code>, 104<code>int</code>, <code>short</code>, <code>char</code>, <code>byte</code>, 105<code>double</code>, <code>float</code> and <code>boolean</code> should be enclosed 106in <code></code>.</p> 107 108<h4>Classes/Interfaces/Methods</h4> 109<p>Use a short description of what the class/interface/method is used for, 110enclose with <p></p>.</p> 111 112<p>A longer description about what the class/interface/method is used for 113and if it is needed how it is done. If it is necessary include 114description of the parameters, what they are used for and how. Enclose 115with <p></p> where it is needed, try to divide into smaller parts (not 116to small!) to enhance readability of the generated Javadoc.</p> 117 118<p>If an example is needed enclose it with <pre></pre>. 119It should be supported with an explanation within a normal paragraph.</p> 120 121<h4>Exception throwing</h4> 122<p>When throwing an exception to indicate a bad argument, always try to throw 123IllegalArgumentException, even if the argument was null. Do not throw 124NullPointerException. (Obviously, you should document what the code actually does!)</p> 125 126<h4>Deprecations</h4> 127<p>When deprecating a method or class include a clear reference to when the method will be deleted. 128This should be of the form 'Method will be removed in Commons Lang 3.0.'. </p> 129 130<h4>Language used in code/comments</h4> 131<p>It has been decided to casually standardize on US-English. 132To avoid misplaced jeers of 'americanisation', the people making this decision largely write in non-US-English. 133However, it's not something to get worked up about. Lots of spelling differences will creep in all over.</p> 134 135<a name="Building"></a> 136<h3>5.BUILDING</h3> 137<h4>Building a Release</h4> 138<p> 139The currently targeted version of Java is 1.6. 140</p> 141<p> 142To build Lang: 143<table> 144<tr><th></th><th>Tested JAR</th><th>Distribution</th><th>Site</th></tr> 145<tr><td>Maven 2.x</td><td><code>mvn package</code></td><td>mvn assembly:assembly</td><td>mvn site</td></tr> 146</table> 147</p> 148</section> 149</body> 150</document> 151