Coding Standards

This document describes a list of coding conventions that are required for code submissions to the project.

Please follow these conventions closely. It makes life so much easier.

Brackets should begin and end on a new line. Examples:

if( foo )
{
    // code here
}

try
{
    // code here
}
catch( final Exception bar )
{
    // code here
}
finally
{
    // code here
}

while( true )
{
    // code here
}

The preference is to include extra spaces between parenthesis and expression. For example;

if( foo )

4 spaces. NO tabs. Period. We understand that a lot of you like to use tabs, but the fact of the matter is that in a distributed development environment, when the svn commit messages get sent to a mailing list, they are almost impossible to read if you use tabs.

In Emacs-speak, this translates to the following command:

(setq-default tab-width 4 indent-tabs-mode nil)

In vim, having the following in your .vimrc will help:

set tabstop=4
set expandtab
set list
set listchars=tab:>.

Unix linefeeds for all .java source code files. Other platform specific files should have the platform specific linefeeds.

Javadoc SHOULD exist on all public and protected methods.

The DPML License MUST be placed at the top of each and every file.

If you contribute to a file (code or documentation), add yourself as the copyright source at the beggining of the file. For .java files the preferred Javadoc format is:

 * Copyright [YEAR] [FULL-NAME].

Indent comments on an 80 column basis and the code on a 100 column basis.

We focus on readability over performance. Source code optimization is the last thing to be done to increase performance. If the code is not performing then it is better to re-engineer it rather than to expand loops, take out variable declarations etc. When the code is stable and has a well defined purpose and interface it may be appropriate to do source code optimization.

Try to javadoc all methods and variables, especially public, protected and default access methods and member variables. Also add code comments when you think it's necessary (like assumptions).

Variables are declared in the inner scope.

while( myListIterator.hasNext() )
{
    final String myString = (String) myListIterator.next();
}

Variables should be descriptive and ideally English words. The exceptions being loop counters (usually use i, j and k), exceptions (use concatenation of word separating characters - i.e. SocketException is abbreviated as se) and other commonly used abbreviations (i.e. sb for StringBuffer).

try
{
    for( int i=0; i<10; i++ )
    {
        // some stuff
    }
}
catch( final FileNotFoundException fnfe )
{
    // some stuff
}
catch( final IndexOutOfBoundsException ioobe )
{
    // some stuff
}

Use String concatenation except in extremely performance sensitive sections. This leaves StringBuffer optimization to the compiler. So use:

final String myString = "test " + "for " + "performances";

Try not to declare a method as 'synchronized'. If a method accesses a shared resource then surround accesses to that resource with a synchronized block. Ideally the synchronized block should surround the smallest possible area. For example:

public void sharedMethod()
{
    String display = null;

    synchronized( this )
    {
        display = mySharedObject.getHelloWorld();
    }

    System.out.println( display );
}

If you are within a static method, then you may have to create a static object whose sole purpose in life is to provide the lock you need. Alternatively you could use the Class object for the class you are in. That is, if you're in class MyClass, use "MyClass.class".

Have the names of all member instance fields start with the prefix "m_". Example:

class MyClass
{
    Class m_class = MyClass.class;
    int m_users;
}

Don't chain method calls. The below:

Thing thing = (MyThing)myObject.doSomething().doSomethingElse().getMyThing();

is considered bad practice because it hides problems relating to synchronization, resource management, etc. The example above might become:

final MySomething something = myObject.doSomething();
final MyElse somethingElse = something.doSomethingElse();
Thing thing = somethingElse.getMyThing();

The extra typing will help keep the code bug-free.

Thanks for your cooperation.

- The DPML Team