src/site/xdoc/developerguide.xml - commons-text - Git at Google

 <!--
 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 &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 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>
	<!--
	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>