Gwydion Style Guide for Java

The Gwydion Group has developed a set of guidelines for programming in Java. Since we have it, we figured we might as well share it with the rest of the world. Except for what's mentioned in the Hypercode Style section, this style guide has nothing to do with Sheets.

We generally follow the "standard" Java style, as exemplified by Sun's books and the code distributed with the JDK. Our major departures are documentation comments and order of declarations.

Note on terminology: Most things in this guide are mandatory -- if you don't follow them, you're in violation of the style guide. (Whether you care is up to you) However, on some issues there is no real consensus. In that case, there is usually a recommended style, and an acceptable style. The recommended style is the style recommended to people with no real opinions on the issue, while the acceptable style allows dissidents to fall within the bounds of good style.

General

An indent level is two spaces. All code must be formatted for an 80 character wide display.

Open curly braces belong on the same line as the thing which opened them:

    if (foo) {
      bar();
    }

rather than

    if (foo)
    {
      bar();
    }

An exception to this rule is made for function headers; see section on definitions for details.

Naming Conventions

Identifiers should follow the Java mixedCase convention. Classes and constructors should begin with uppercase letters, and fields and methods should begin with lower case letters. The only exception is for constants (static final fields), which are all uppercase and use underbars to separate words. Examples:

    class NormalClass {
      int normalField;
      static final int CONSTANT_FIELD;
    } 

Subclasses will often be named by taking the superclass and adding an adjective to the front of it. For instance, one subclass of Dialog is named FileDialog.

Method names are usually verb phrases (preferred), like updatePreview, or properties of the class (less preferred), like allTokens. Methods that return booleans should begin with is, as in isString. Methods that act as simple wrappers for fields should be named getField and setField, respectively.

Usually, methods that take an index into a collection should use the word At in the name, as in setElementAt. Similarly, methods that find elements in a collection should generally end in the word Of, as in indexOf. (The Java Beans style guide suggests an alternate convention for the first form, omitting the word At. The Java language alternates between including At and omitting it.)

Definitions

In Java, definitions are class headers, methods, fields, and constructors. (They are sometimes referred to as top level forms, but this is not really accurate because they can be nested) The word function is used to mean method or constructor.

Definitions should be separated by a blank line (and not by a blank comment line).

For all definitions, it is suggested that access control modifiers (public, protected, and private) go first, then synchronized or transient, then static or abstract, then final.

The Gwydion Group does not follow the Java convention of ordering class members by access control. The Java convention is to declare public members first, then protected members, then package, then private, and within each level put fields before methods. We prefer to organize our code by concept, not access control.

For definitions with bodies, the curly braces may go in any of three places:

    header { body }

    header {
      body
    }

    header
    {
      body
    }

It should be emphasized that this is the only time an open curly brace may go on a blank line.

Long class headers may be broken before an extends or implements clause. The new lines should be indented two indent levels.

Field definitions may be broken before the = sign, just like a local variable declaration (see next section). The new line should be indented a single indent level.

Function headers should have a space between the function name and the parameter list. Long function headers may be broken in either of two places:

• Inside the parameter parenthesis after a comma
• After the function's name and before the open paren of the parameters specification

In the first case, the new lines should be indented two indent levels (four spaces). In the second case, the lines should be indented just inside the open paren of the parameter parenthesis (that is, one column beyond the column of the open paren).

Examples:

    // Style 1
    static boolean shadows (JavaFunctionComponent specific, 
                            JavaFunctionComponent general)

    // Style 2
    static boolean shadows
        (JavaFunctionComponent specific, JavaFunctionComponent general)

If the function contains a throws clause, the header may be broken directly before it, indenting the new line two levels.

Functions should not be too long. What constitutes "too long" is obviously a judgment call, and will vary by circumstance as well as by author. Nick's guideline is that functions should fit in one screenful (roughly 35 lines).

Statements

Statements with braces should have the opening curly brace on the same line as the beginning of the statement. If the statement has intermediate keywords (like the else in an if statement), it is recommended that the intermediate keyword share a line with a close curly brace, if possible.

It is acceptable but by no means required to use braces when they are not syntactically required.

There should always be a space following any comma or semicolon, and any colon used as part of a label (both break labels and case labels). Curly braces and statement keywords (if, for, switch, etc.) must always be surrounded by whitespace.

There are two preferred ways to format an if statement, and two acceptable but not recommended ways:

    // one liner format
    if (foo) { bar(); } else { baz(); }
 
    // multi-line format
    if (foo) {
      bar();
    } else {
      baz();
    }
 
    // "William style" multi-line if -- not recommended
    if (foo) {
      bar();
    } 
    else {
      baz();
    }
 
    // condensed multi-line format -- not recommended
    if (foo) { bar(); }
    else { baz(); }

Obviously, braces and else clauses can be omitted.

In an else if construct, the else and the following if should go on the same line:

    if (foo) {
      bar();
    } else if (quux) {
      baz();
    }

    try {
      body();
    } catch (Error e) {
      handleIt();
    } finally {
      doSomething();
    }

    case LABEL: foo(); break;
 
    case LABEL:
      foo(); break;
 
    case LABEL:
      foo();
      break;

    for (int i = 0; i < 10; i++) {
      whatever();
    }

      someCode();
    bigLoop:
      for (int i = 0; i < 10; i++) {
        if (something)
          break bigLoop;
      }
      postLoop();

    String type 
      = exprType(balanceRBracket(index - 1) - 1, context);

    ! ~ ++ --

    + - * / % ^ & && | || << >> >>>
    += -= *= /= %= ^= &= |= = <<= >>= >>>=
    == != <= < > >=

    if (foo+1 < 10)

    if (token.kind == JavaParserConstants.BOOLEAN
          || token.kind == JavaParserConstants.CHAR
          || token.kind == JavaParserConstants.BYTE)

    (condition) ? x : y
 
    (condition) ? x
                : y
 
    (condition)
      ? x // indented one indent level
      : y

    g.drawString(view.dispLines[line2].substring(0, ind2 + 2), 0,
                 base + line2 * view.lineHeight());

    methodWithAReallyLongName
      (view.dispLines[line2].substring(0, ind2 + 2), 0,
       base + line2 * view.lineHeight());

    something.somethingElse.somethingElseStill.gettingLongerByTheMinute
      .drawString(foo, bar);

    // Comment
    int foo;

    // Paragraph 1
    //
    // Paragraph 2
    int foo;

    int localVariable = 3; // This is a same line comment

    // Wrong
    int someVar       = someValue;
    int longerVarName = someOtherValue;
    int x             = 3;

    // Right
    int[] foo;
 
    // Wrong
    int foo[];