|
Developer guide for Commons "Text"The Commons Text PackageDevelopers Guide[Introduction] [Package Structure] [Utility Classes] [Javadoc] [Building] 1. INTRODUCTIONThe Text 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. The philosophy of the naming standards is to follow those of the JDK if possible. 2. PACKAGE STRUCTUREThe main package for Text is org.apache.commons.text. Subpackages should be created for each group of related items. Each package should have a package.html file for javadoc. This should describe the use of the package and its scope. 3. UTILITY CLASSESUtility classes provide additional functionality around a class or interface. Examples include StringUtils and StringEscapeUtils. Each class shall follow the naming pattern XxxUtils where Xxx relates to the class or interface that the utility services. Variations on a theme (Integer as opposed to Number) should be dealt with in one Utils class where possible. Each Utils class shall:
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. 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. 4. JAVADOCThe 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. GeneralReferences 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>. References to null, this, long, int, short, char, byte, double, float and boolean should be enclosed in <code></code>. Classes/Interfaces/MethodsUse a short description of what the class/interface/method is used for, enclose with <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. If an example is needed enclose it with <pre></pre>. It should be supported with an explanation within a normal paragraph. Exception throwingWhen 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!) DeprecationsWhen 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.'. Language used in code/commentsIt 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. |