commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject cvs commit: jakarta-commons/lang DEVELOPERS-GUIDE.html
Date Sun, 22 Dec 2002 21:07:35 GMT
scolebourne    2002/12/22 13:07:35

  Added:       lang     DEVELOPERS-GUIDE.html
  Log:
  First version of Lang developers guide
  
  Revision  Changes    Path
  1.1                  jakarta-commons/lang/DEVELOPERS-GUIDE.html
  
  Index: DEVELOPERS-GUIDE.html
  ===================================================================
  <html>
  <head>
  <title>Developers guide for Jakarta Commons "Lang" Package</title>
  <head>
  <body bgcolor="white">
  
  
  <div align="center">
  <h1>The Jakarta Commons <em>Lang</em> Package</h1>
  <h2>Developers Guide</h2>
  $Id: DEVELOPERS-GUIDE.html,v 1.1 2002/12/22 21:07:35 scolebourne Exp $<br />
  <a href="#Introduction">[Introduction]</a>
  <a href="#PackageStructure">[Package Structure]</a>
  <a href="#UtilityClasses">[Utility Classes]</a>
  <a href="#Javadoc">[Javadoc]</a>
  <br /><br />
  </div>
  
  
  <a name="Introduction"></a>
  <h3>1.  INTRODUCTION</h3>
  
  <p>The <em>Lang</em> package contains a set of Java classes that extend
  the basic JDK classes. This developers 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 Lang is <code>org.apache.commons.lang</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 SerializationUtils.</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>
  </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>
  
  
  
  <a name="Javadoc"></a>
  <h3>4.  JAVADOC</h3>
  
  <p>The Sun javadoc guidelines are the starting point for Lang. 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 nessesary 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>
  
  </body>
  </html>
  
  
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message