Huihoo.org - Open Enterprise Foundation

CODE STYLE GUIDE


(来源:http://www.jboss.com)

This guide is here to make the JBoss code more readable. Because of the age of JBoss there will be always some code around which does not follow this guide, but over time this will become less and less.

Layout

Identation
3 Spaces (no Tabs because they look ugly in "dump" editors like HTML pages (online CVS)).
Comments
Line up comments on the left hand side (also Javadocs).
Grouping
Group members, methods etc. according to the templates and use the template's comments to separate them.

General Code

The first part of a JBoss class should contain the Copyright comment:

/*
 * JBoss, the OpenSource J2EE webOS
 *
 * Distributable under LGPL license.
 * See terms of license at gnu.org.
 */
   

Next part is the package definition. Please use NO ABBREVIATIONS and follow the Java guidelines.

Now add the external classes import statement. Please use always fully qualified imports (no *) because then everyone knows which class comes from which package. When you have a conflict then import none or the best one and fully qualify the other class(es) when you use them (example: java.util.Date and java.sql.Date).

Add the JavaDoc documentation for the main class which looks like this:

/**
 * <description> 
 *
 * @see <related>
 *
 * @author  <a href="mailto:{email}">{full name}</a>.
 * @version $Revision: 1.2 $
 *   
 * <p><b>Revisions:</b>
 *
 * <p><b>yyyymmdd author:</b>
 * <ul>
 * <li> explicit fix description (no line numbers but methods) 
 *            go beyond the cvs commit message
 * </ul>
 *    eg: 
 * <p><b>20010516 marc fleury:</b>
 * <ul>
 * <li> Ask all developers to clearly document the Revision, 
 *            changed the header.  
 * </ul>
 */
      

NOTE: The above is a guide for creating class javadocs. There are certain sections (<description>, <related>, ...) which are meant to be replaced by the individual developer as it applies to the class at hand. Please DO NOT cut and pase this example with out replacing these tokens.

Instead of @see you can also use {@link ...} inside the comments (inline reference). ALWAYS add these comments, the developer after you will love it and hopefully do his/her part as well.

Document all public (and mostly protected) members and methods in the class with JavaDoc except you did not add new functionality during overwriting a method (comming from an Interface or a base class). Especially note the following:

  • When Parameter can or cannot be null and also what it means when null is allowed.
  • When Return values can be or are never null.
  • Document side effects.
  • Usefull is also when you mention if and where another method or the overwritten method is called. Because this is open-source it is not that important but when you only rely on the documentation it can avoid endless calls or other avoid mistakes when you have to call the overwritten method.
  • Please add JavaDoc to every method/class when you working on this page. When you are not 100% sure about what you read please enlose the changed lines into "<review>" and "</review>" to indicate what you changed and gave up for a review. When someone reviewed it just remove this marks, thanx.

Coding a Class

/*
 * JBoss, the OpenSource J2EE webOS
 *
 * Distributable under LGPL license.
 * See terms of license at gnu.org.
 */

package x;

// EXPLICIT IMPORTS
import a.b.C1; // GOOD
import a.b.C2;
import a.b.C3;

// DO NOT WRITE
import a.b.*;  // BAD

// DO NOT USE "TAB" TO INDENT CODE USE *3* SPACES FOR PORTABILITY AMONG EDITORS

/**
 * <description> 
 *
 * @see <related>
 * @author  <a href="mailto:{email}">{full name}</a>.
 * @author  <a href="mailto:marc@jboss.org">Marc Fleury</a>
 * @version $Revision: 1.2 $
 *   
 * <p><b>Revisions:</b>
 *
 * <p><b>yyyymmdd author:</b>
 * <ul>
 * <li> explicit fix description (no line numbers but methods) go 
 *            beyond the cvs commit message
 * </ul>
 *  eg: 
 * <p><b>20010516 marc fleury:</b>
 * <ul>
 * <li> Ask all developers to clearly document the Revision, 
 *            changed the header.  
 * </ul>
 */
public class X
   extends Y
   implements Z
{
   // Constants -----------------------------------------------------
   
   // Attributes ----------------------------------------------------
   
   // Static --------------------------------------------------------
   
   // Constructors --------------------------------------------------
   
   // Public --------------------------------------------------------
   
   public void startService() throws Exception
   { // Use the newline for the opening bracket so we can match top and bottom bracket visually
      
      Class cls = Class.forName(dataSourceClass);
      vendorSource = (XADataSource)cls.newInstance();
      
      // JUMP A LINE BETWEEN LOGICALLY DISCTINT **STEPS** AND ADD A LINE OF COMMENT TO IT
      cls = vendorSource.getClass();
      
      if(properties != null && properties.length() > 0)
      {
      
         try
         {
         }
         catch (IOException ioe)
         {
         }
         for (Iterator i = props.entrySet().iterator(); i.hasNext();)
         {
            
            // Get the name and value for the attributes
            Map.Entry entry = (Map.Entry) i.next();
            String attributeName = (String) entry.getKey();
            String attributeValue = (String) entry.getValue();
            
            // Print the debug message
            log.debug("Setting attribute '" + attributeName + "' to '" +
               attributeValue + "'");
            
            // get the attribute 
            Method setAttribute =
            cls.getMethod("set" + attributeName,
               new Class[] { String.class });
            
            // And set the value  
            setAttribute.invoke(vendorSource,
               new Object[] { attributeValue });
         }
      }
      
      // Test database
      vendorSource.getXAConnection().close();
      
      // Bind in JNDI
      bind(new InitialContext(), "java:/"+getPoolName(),
         new Reference(vendorSource.getClass().getName(),
            getClass().getName(), null));
   }

   // Z implementation ----------------------------------------------
   
   // Y overrides ---------------------------------------------------
   
   // Package protected ---------------------------------------------
   
   // Protected -----------------------------------------------------
   
   // Private -------------------------------------------------------
   
   // Inner classes -------------------------------------------------
}
      

Coding an Interface

/*
 * JBoss, the OpenSource J2EE webOS
 *
 * Distributable under LGPL license.
 * See terms of license at gnu.org.
 */

package x;

// EXPLICIT IMPORTS
import a.b.C1; // GOOD
import a.b.C2;
import a.b.C3;

// DO NOT WRITE
import a.b.*;  // BAD

// DO NOT USE "TAB" TO INDENT CODE USE *3* SPACES FOR PORTABILITY AMONG EDITORS

/**
 * <description> 
 *
 * @see <related>
 * @author  <a href="mailto:{email}">{full name}</a>.
 * @author  <a href="mailto:marc@jboss.org">Marc Fleury</a>
 * @version $Revision: 1.2 $
 *   
 * <p><b>Revisions:</b>
 *
 * <p><b>yyyymmdd author:</b>
 * <ul>
 * <li> explicit fix description (no line numbers but methods) go 
 *            beyond the cvs commit message
 * </ul>
 *  eg: 
 * <p><b>20010516 marc fleury:</b>
 * <ul>
 * <li> Ask all developers to clearly document the Revision, 
 *            changed the header.  
 * </ul>
 */
public interface X
   extends Y
{
   int MY_STATIC_FINAL_VALUE = 57;

   ReturnClass doSomething() throws ExceptionA, ExceptionB;
   
}