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