Java Persistent Objects - Design : Programming Guidelines

JPOX Design : Programming Guidelines

This document describes a collection of standards, conventions, and guidelines for writing solid Java code. They are based on sound, proven software engineering principles that lead to code that is easy to understand, to maintain, and to enhance. Furthermore, by following these coding standards your productivity as a Java developer should increase remarkably. Experience shows that by taking the time to write high-quality code right from the start, you will have a much easier time modifying it during the development process. Finally, following a common set of coding standards leads to greater consistency, making teams of developers significantly more productive." Ambler

"Coding standards for Java are important because they lead to greater consistency within your code and the code of your teammates. Greater consistency leads to code that is easier to understand, which means it is easier to develop and to maintain. This reduces the overall cost of the applications that you create.

You have to remember that your Java code will exist for a long time; long after you have moved on to other projects. An important goal during development is to ensure that you can transition your work to another developer, or to another team of developers so they can continue to maintain and enhance your work without having to invest an unreasonable effort to understand your code. Code that is difficult to understand runs the risk of being scrapped and rewritten." Ambler

This document provides a general overview on JPOX coding standards. We recommend you to read the references provided in this document prior to starting coding, and never use coding conversions from C++ or Visual Basic, we are doing Java!

Code Formatting

There follows a selection of standards that we have adopted on JPOX that should be observed when checking in code. The majority of IDE's such as JBuilder and Eclipse have code formatting tools that can be configured to do this for you. Within the Maven "site" command the Checkstyle process is run generating a report on the compliance with these standards. Please use it. In addition the PMD report gives more information regarding the coding standards.

Insert a new line before an opening brace
Insert new lines in control statements
Insert a new line inside an empty block
Maximum line length: 120 for comments, 140 for code
Number of spaces representing a tab: 4
Do NOT use tabs in source files. They mess up the view when someone with a different tab setting opens it.
Always fully specify imports, and do not use * notation. This makes resolving references very difficult and it is better that you specify what class you are importing so as to understand it better.

If you are using Eclipse, we provide the xml configuration for the code conventions. Eclipse code conventions

{
    if (size < currentSize)
    {
        try
        {
            size = inStream.available();
        }
        catch (IOException e)
        {
        }
    }
    else if (size == currentSize)
    {
        ++size;
    }
    else
    {
        --size;
    }
}

/**
 * A sample source file for the code formatter preview
 */
package mypackage;

import java.util.LinkedList;

public class MyIntStack
{
    private final LinkedList fStack;

    public MyIntStack()
    {
        fStack = new LinkedList();
    }

    public int pop()
    {
        return ((Integer) fStack.removeFirst()).intValue();
    }

    public void push(int elem)
    {
        fStack.addFirst(new Integer(elem));
    }

    public boolean isEmpty()
    {
        return fStack.isEmpty();
    }
}

/**
 * Indentation
 */
class Example
{
    int[] myArray = {1, 2, 3, 4, 5, 6};
    int theInt = 1;
    String someString = "Hello";
    double aDouble = 3.0;

    void foo(int a, int b, int c, int d, int e, int f)
    {
        switch (a)
        {
            case 0 :
                Other.doFoo();
                break;
            default :
                Other.doBaz();
        }
    }

    void bar(List v)
    {
        for (int i = 0; i < 10; i++)
        {
            v.add(new Integer(i));
        }
    }
}

/**
 * Braces
 */
class Empty
{
}

class Example
{
    SomeClass fField = new SomeClass()
    {
    };
    int[] myArray = {1, 2, 3, 4, 5, 6};

    Example()
    {
    }

    void bar(int p)
    {
        for (int i = 0; i < 10; i++)
        {
        }
        switch (p)
        {
            case 0 :
                fField.set(0);
                break;
            default :
                fField.reset();
        }
    }

    void foo()
    {
    }
}

/**
 * Declarations
 */
class MyClass implements I0, I1, I2
{
}


AnonClass = new AnonClass()
{
    void foo(Some s)
    {
    }
};


int a = 0, b = 1, c = 2, d = 3;


int a = 0, b = 1, c = 2, d = 3;


MyClass() throws E0, E1
{
    this(0, 0, 0);
}

MyClass(int x, int y, int z) throws E0, E1
{
    super(x, y, z, true);
}


void foo() throws E0, E1
{
};

void bar(int x, int y) throws E0, E1
{
}


label : for (int i = 0; i < list.length; i++)
{
    for (int j = 0; j < list[i].length; j++)
    {
        continue label;
    }
}

/**
 * New Lines
 */
private class Empty
{
}

class Example
{
    static int[] fArray = {1, 2, 3, 4, 5};
    Listener fListener = new Listener()
    {
    };

    // the following line contains line breaks
    // which can be preserved:
    void bar()
    {
    }

    void foo()
    {
        ;;
        do
        {
        }
        while (false);
        for (;;)
        {
        }
    }
}

/**
 * If...else
 */
class Example
{
    void bar()
    {
        do
        {
        }
        while (true);
        try
        {
        }
        catch (Exception e)
        {
        }
    }

    void foo2()
    {
        if (true)
        {
            return;
        }
        if (true)
        {
            return;
        }
        else if (false)
        {
            return;
        }
        else
        {
            return;
        }
    }

    void foo(int state)
    {
        if (true)
        {
            return;
        }
        if (true)
        {
            return;
        }
        else if (false)
        {
            return;
        }
        else
        {
            return;
        }
    }
}

Localisation

JPOX operates using a system for internationalisation of information output to the user. This revolves around the org.jpox.util.Localiser class. If you are going to output information to users, you should put all of your information in a file Localisation.properties in the directory where your class is, and use the Localiser class to extract the parameter for your information. Do NOT put string information in Java files. Please refer to the Localisation guide for details.

Debugging

System.out and System.err should NOT be used in JPOX, unless the module is part of a utility application (e.g SchemaTool, or the enhancer process). Core JPOX code should have NO System.out/err lines. Use Logging where you need to output any information for debugging purposes.