Navigation: ()

Coding Conventions

As in the memorable line from "The Pirates of the Caribbean" when discussing about the Code of the pirates, "They are not laws, more like guidelines...".

Please use the Sun Java Standards with the following additional caveats/replacements.

Java Coding Conventions

The following are coding conventions to be followed when using Java for Topaz.

• When adding code to existing open source products to be submitted back to them, use their guidelines
• Follow Sun conventions in general
• 2 space indent (please note: set your editor to use spaces and not tabs)
• No wildcard imports (no import java.io.*). Use each class import separately.
• Max line 100 characters
• Use // for one line comments only and /* */ for multiline comments
• { should be put on the same line
• Single line "if" etc. do not need {}
• Conditionals should always be on a new statement. The following is incorrect:

  if (...) ....
  

  It should be

  if (...)
    ....
  

  or

  if (....) {
    ....
  }
  

• Java doc for all functions (including private methods) and index.html for all packages with examples on how to use it (more below)
• javadocs for all non-private fields
• always a space before { (no "try{" etc)
• Do not check in commented out code. That is not a replacement for proper comment. Add a psuedo algorithm if necessary. Checking in commented out debug statements is also not recommended.
• proper } bracing:

  try {
    ...
  } catch (...) {
    ...
  }
  

  not

  try {
    ...
  }
  catch (...) {
    ...
  }
  

• This is a biggy: always chain exceptions properly! The following is a complete no-no:

  catch (ServletException e) {
    throw new IOException(e.getMessage());
  }
  

  This throws away the stack trace. Never, ever, do that! At the very least log it, but in this case since your throwing a new exception then use the exception chaining:

  catch (ServletException e) {
    throw (IOException) new IOException("Failed to get service").initCause(e);
  }
  

• Do not use Java assertions for checking method parameters; use them only for internal consistency checking within a single class. Parameter checking should be done with the usual if statement and throwing an appropriate exception (usually IllegalArgumentException or NullPointerException for nulls).
  
  When using assertions always provide a message with some info containing what the expected and the actual values were.

Java Header

The following should appear at the top of every topaz source file:

/* $HeadURL$
 * $Id$
 *
 * Copyright (c) 2006-2008 by Topaz, Inc.
 * http://topazproject.org
 *
 * Licensed 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.
 */

package ...

JavaDocs

All methods that are not private must have javadocs; private methods should have javadocs too, but they can omitted for very simple methods. All parameters, return values, and exception must be documented. Furthermore all classes must have javadocs. And lastly, all non-private fields must also have javadocs.

Note, however, that this rule applies to the generated documentation. Since javadoc supports inheritance on method comments, this means that in a number of cases the javadocs can be omitted in the code. For example, when implementing an interface it is not necessary to write any javadocs for those implemented methods, as they will inherit the javadocs from the interface (in fact, it's recommended not to write any javadocs as they would really be a duplicate of what's on the interface and hence could get out of sync if their updated on the interface). Feel free to also make use of the @inheritDoc tag. More info in inheritance can be found in the javadoc Documentation on Sun's site.