| <!-- |
| 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 "Text"</title> |
| </properties> |
| <body> |
| |
| <!-- $Id$ --> |
| |
| <section name='Developer guide for Commons "Text"'> |
| |
| <h1>The Commons <em>Text</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 /> |
| |
| <a name="Introduction"></a> |
| <h3>1. INTRODUCTION</h3> |
| |
| <p>The <em>Text</em> package contains a set of Java classes that contain algorithms for measuring |
| and manipulating string. 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 Text is <code>org.apache.commons.text</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 StringEscapeUtils.</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 Text. 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 Text 2.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> |
| The currently targeted version of Java is 1.7. |
| </p> |
| <p> |
| To build Text: |
| <table> |
| <tr><th></th><th>Tested JAR</th><th>Distribution</th><th>Site</th></tr> |
| <tr><td>Maven 3.x</td><td><code>mvn package</code></td><td><code>mvn assembly:assembly</code></td><td><code>mvn site</code></td></tr> |
| </table> |
| </p> |
| </section> |
| </body> |
| </document> |