Navigation: ()

Coding Conventions

Most developers have very strong opinions on coding conventions and without a manadated set of standards tend to use their own best format leading to a source base having multiple look and feel and annoying to work consistently in text editors. To avoid this (and the endless debates which one can have on this subject), Topaz/Ambra have adopted a coding convention that hopefully is an optimal solution.

The premises these conventions have been based on are as follows:

  • Readability: All code should be readable (and this covers all files checked into the source code repository, not just Java files). This entails the following:
    • Keeping information in files as sparse as possible: Please do not use source code files to maintain history or as a scratch pad for design ideas. Source code tools provide good information on history of changes to files and the wiki should be used for design idea.
    • Please do not 'tag' code with your names, dates, etc. If you feel the need to add your name as an author to a file add it at the beginning of the file.
    • For all files in our control (that is not copied from other projects):
      • Line length should not exceed 100 characters
      • Indentation should be two space characters (please do not use tab characters for indentation)
  • Consistency: It is imperative that file formatting remains the same as far as possible. This really helps new developers in reading and understanding the code base. So please use the existing format of a file you are editing (for new files see below). However, if the file is under our control, wrong formatting should be fixed as and when you notice them.
  • Editor independence: Allow use of different editors (and avoid 'my editor is better than yours' debate)
  • File system/OS independence: Allow use of different operating systems (and avoid 'my os is better than yours' debate)
  • Shared costs: Everyone is responsible for maintaining good readable code

If you are unsure:

  • Please look at other files of the same type within the project and follow that formatting scheme.
  • Ask on the appropriate mailing list

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...". Changes to the convention however should be discussed with other developers on the appropriate mailing lists first.

Java Coding Conventions

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

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. The following is an example of a valid multiline comment: 
           /*
        * Callback does not throw exception. We need to pass Exception object in the return
        * parameter so we can throw it in the calling method.
        */
    Please note the column allignment for * in each line.
  • { 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-2009 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.

IDE Setup

  • For setting up code style in Intellij IDEA see IDEASetup

Attachments