The Zinc project coding standards are based on Sun Microsystems' Code Conventions for the Java™ Programming Language. This document serves as a quick reference to the main points of our coding standards.

• Back to the Developers' Page

Code Layout

The following rules should be observed when writing code for Zinc.

• No hard tabs. Use spaces rather than hard tabs. This is so that source files display the same in all editors.

• No line should be longer than 80 characters. Again this is to ensure that source files are viewable in all editors. It also means that files will print correctly.

• Always use four spaces for indentation. The only exception to this is a continuation line, which should be indented by only two spaces.

• BSD/Allman bracketing style should be used (curly brackets on separate lines lining up with the first character of the statement they belong to).

• There should be no whitespace between function names/statements and opening parenthesis e.g. if(a == b) rather than if (a == b).

  Conversely, there should be whitespace in expressions to aid clarity e.g. a = b * c + d rather than a=b*c+d. a = b*c + d is acceptable because it makes the operator precedence clear.

• Function and variable names should be mixed case with a lower case first letter e.g. variableName rather than VariableName, variablename or variable_name.

  Constants should be capitalized with underscores between words e.g. CONSTANT_NAME.

  Class names should be in mixed case e.g. ClassName.

• If a switch statement contains a fall through then it should have a comment explaining the intention of the fall through.

• Javadoc comments should be used for public and protected methods and variables. Javadoc comments should be layed out as shown in the example below.

An example of correct Zinc code is below:

public class MyClass
{
    /** A one line javadoc comment. */
    public int variable;


    /** A constant. */
    public final static int OUR_CONSTANT = 42;

    
    /**
     *   Summary of this function.
     *   <p>
     *   Now the javadoc comment contains
     *   extra information about the function.
     *   Note the use of paragraph tags
     *   between each paragraph.
     *   <p>
     *   And another paragraph...
     *
     *   @param argument some notes about
     *     the argument.
     */
    public void myFunction(int argument)
    {
        if(argument == 1)
        {
            // Do some stuff
        }
        else
            argument = 0;

        // An example of a long line
        if(argument == 1 || argument == 2
          || argument == 3 || argument == 5
          || argument == 7 || argument == 11
          || argument == 13)
            doSomething(argument);

        // A switch statement with fall throughs
        switch(argument)
        {
            case 1:
                doStuff();
                break;

            // These all fall through
            case 2:
            case 3:
            case 4:
                doSomething();
                break;

            case 5:
                wibble();
                // Fall through
            case 6:
                wibbleWobble();
                break;
        }
    }
}

Use of Assertions

Zinc takes advantage of the assertion mechanism introduced in the Java language with version 1.4. To use assertions Zinc has to be compiled with the command javac -source 1.4 .... By default assertions are turned off at run time. To enable them run Zinc with the -ea flag e.g. java -ea Zinc.

Assertions have two forms:

assert expression;

or

assert expression : "Expression was not true!";

In each form the assertion will check that expression is true. If it is not then the program will throw an AssertionError exception. AssertionError exceptions do not have to be explicitly caught.

The second form will display a more meaningful error message. Specifically it will display the string form of the object after the colon. Usually you would place a string literal after the colon, but you may use any object.

For more information about assertions and how they should be used see Programming With Assertions.