Style Conventions

Javadoc and Comments

$/!\$ Important $/!\$

All new code must contain complete javadoc comments both for public and private fields and methods. Existing code should be brought up to this standard as soon as practicably possible. Liberal(non-javadoc) comments in other areas is also highly encouraged.

Please remember that other developers may have a hard time understanding your code and that making the effort to write a little bit of quality documentation (in the code or otherwise) can often make a world of difference for those that must maintain your code later.

Formatting

For those who use the Eclipse IDE, this format file: format.xml may be useful for automating the formatting conventions that are described below (this was created with Eclipse 3.3).

Braces

Opening braces go on a new line, eg

public static void main(String args[])
{
  while(true)
  {
    //Don't leave empty braces without a reason for it!
  }
}

Single lines should be enclosed in braces.

The exception to this is array initialization if used:

int [] array = {1,2,3,4}

Tabbing

Tabbing should be done with spaces. Each level of indentation should take up 2 spaces.

Imports

Each class being imported should be on a separate line. Do not use wildcard imports.

Sorting

Class members should be sorted in the following order:

static variables
static functions
inner classes
class member variables
constructors
class member functions

Each group of members should be sorted with public first, then protected, default and private items.

Additionally each group should be sorted alphabetically.

JavaScript code

For the most part, the same guidelines as above should be followed.

Many Java developers forget that variables in JavaScript only have function scope (there is no block level scope) so be sure to take care to define your vars at the function level. JavaScript is very forgiving if you don't, but it could lead to bugs later.

For example,

function myFunc(a,b)
{
  for (var i=0; i<a.length; i++)
  {
    otherFunc(a,i);
  }

  if (b)
  {
    var i = b+5;
    return i;
  }
}

should be written as

function myFunc(a,b)
{
  var i;
  for (i=0; i<a.length; i++)
  {
    otherFunc(a,i);
  }

  if (b)
  {
    i = b+5;
    return i;
  }
}

Also, please make sure to try and avoid using eval excessively as it can make the code confusing and hard to follow. Oftentimes there is an easy way to accomplish the same thing without using eval.

It's a great idea to run your JavaScript code through JSLint to clean it up and it's strongly encouraged that you make a habit of doing this.