Coding Conventions for the JavaFX Language

Introduction

This wiki page provides a set of recommendations for how to format your JavaFX code - a coding
style or style guide for JavaFX.

Note that this is not an official document from Sun or the JavaFX team; I do work at Sun and
on JavaFX but there are many people more qualified than me to write with authority on this. I plan
to incorporate their feedback as soon as I get it!

This document is my attempt to

Capture the de-facto conventions I am observing in the JavaFX platform libraries, and
Provide own opinions in cases where there is enough variation that there isn't an obvious
recommended style yet.

I googled looking for existing JavaFX coding conventions and the only thing I came across
was a blog entry with a number of recommendations that don't match the Sun coding style
(for example, it placed left braces on lines by themselves), so I thought it would be worthwhile
to start my own.

I chose to put this in a wiki page rather than in a blog, not just because I can imagine that it will
grow over time, but because I'm also certain that I will be convinced to change this content
over time as we discuss these topics and as the language evolves. Finally, a wiki will allow
collaboration.

This first revision attempts to be brief rather than pedantic.

Default: Stay Consistent with Java

This document only records issues that are specific to JavaFX. For everything else, follow
the general Java code convention. This means:

Use a 4-space indent
Use CamelCase for class names, camelCase for function, method, property and variable names, and
UNDERLINED_CAPS for constants (this does not include local def's)
No spaces directly inside parentheses, or before semicolons
Spaces around operators
Left brace, {, should never be on its own line. For multiline blocks, } should always
be on its own line and line up with the beginning of the block.
Always use { } around if clauses - don't write code like "if (foo) bar()".
Wildcard imports are okay.

File organization

Place private, static constants used by a class at the top of the file. Place everything else
(private utility methods) after the class.

Place public (public, public-init, public-read) properties at the top of the class, followed
by protected, package and finally private properties.

Rather than organizing constructor code into a single big init {} block, use multiple init blocks
if necessary to distribute the code near their logical place. For example, if you are initializing
a map, place the init block next to the declaration of the map.

Type Definitions

There should be no space before a type declaration and one space after it. This is true both
for variable declarations and for parameters. In other words:

var yes: Number;
var no:Number;
var no : Number;
function foo(yes: Boolean, no : Boolean, no:Boolean) { ... }

All non-overriding functions should explicitly state their return type rather
than rely on JavaFX' ability to infer them automatically.

public function foo(): Number { 1 }   // Yes
public function foo(): Integer { 1 }  // Yes
public function foo(): { 1 }          // No

public function foo(): Void { bar() } // Yes

Object Literals

Just as for type definitions, the property name and the property value should
have a single space after the colon.

There should not be any semicolons at the end of a line, including the final closing }.

// Yes
Insets {
    left: 0
    right: 0
    top: 0
    right: 0
}

// No
Insets {
    left:0     // Missing space after :
    right : 0  // Extra space before :
    top: 0;    // Extra semicolon
};             // Extra semicolon

For single-line definition of objects

Multiple properties should be separated by a comma to enhance readability.
Semicolons are okay too but I think commas are preferable.
There should not be a semicolon before (or after) the closing }
There should be a single space inside the left and right braces

Point2D { x: 100, y: 100 }

// No:
Point2D {x: 100, y: 100}    // Missing spaces inside {}
Point2D { x: 100 y: 100 }   // Missing comma separator
Point2D { x:100, y:100 }    // Missing space after :
Point2D { x: 100, y: 100; } // Extra semicolon before }
Point2D { x: 100, y: 100 }; // Extra semicolon after {

When an object literal is defined in indented code, the whole object literal should
be indented such that the final closing } lines up directly with the beginning of
the object literal.

When an object is specified on the right hand side of an assignment, or as a
parameter to a function, or in an insert into expression, or any other context where
the object literal is not the first non-whitespace character on a line, there are
acceptable ways to indent the code block:

// Alternative 1: Indent whole literal to rhs indentation
def shapeInsets = Insets {
                      left: 0
                      right: 0
                      top: 0
                      bottom: 0
                  }

// Alternative 2: Indent to the lhs indentation                 
def shapeInsets2 = Insets {
    left: 0
    right: 0
    top: 0
    bottom: 0
}

// Alternative 3: Indent one level on the next line.
def shapeInsets3 = 
    Insets {
        left: 0
        right: 0
        top: 0
        bottom: 0
    }

I have recently started using form #3 which I think works best in most scenarios.
The problem with #1 is that it doesn't work well in more deeply nested code,
and it doesn't work well when block starts at a character other than a multiple of
the indentation size. The problem with #2 is that it's harder to spot visually
what is created since the class being instantiated doesn't line up with the final }.

For sequences, add a whole indentation level for the sequence begin/end markers ( [ ] ).
Note also that like {, the [ should not appear on its own line:

Group {
    content: [
        Button {},
        Button {}
    ]
}

// No
Group 
{                    // Should not be on its own line
    content: 
    [                // Should not be on its own line
        Button {},
        Button {}
    ]
}

Nested data structures should be declared in place. You may find that you need
to reference one part of the nested data structure from another. But rather than
pulling those parts out and defining them first, you can define variables for
these and assign them as part of the object hierarchy:

var scene: Scene;
Stage {
    width: 1000
    height: 1000
    scene: scene = Scene { // We assign to variable as part of declaration
        content : [
            ListView {
                items: items
                width: bind scene.width
                height: bind scene.height
            }
        ]
    }
}

For large data structures you don't even need to define the variables up front;
you can do it within the declaration:

Group {
    var button: Button; // Button reference defined inside Group literal
    content: [
        button = Button { text: "Hello" }
    ]
    onMouseEntered: function(e) {
        button.effect = DropShadow{};
    }
}

Function Returns

The last statement of the function should evaluate to the return of the function.
Do not use the "return" keyword. And add a blank line before the last statement
(unless it's the only statement of the function).

// Yes - just specify an object literal
function create(args): Foo {
    Foo {
        foo: args.foo
        bar: args.bar
    }
}

function indexOf(str: String): Number {
    ...code...

    -1
}

public override function toString() {
    "{allowed}, but usually in {common}"
}

public bound function getIconPaint():Paint {
    def brightness = UtilsFX.calculateBrightness(BASE_COLOR);

    if(brightness>=0.5 and brightness<0.7) then {
        ICON_COLOR_DARK
    } else if (brightness>=0.5) then {
        ICON_COLOR
    }  else {
        ICON_COLOR_LIGHT
    }
}

Note also that there is no semicolon here – the last statement is "-1" or "null" etc, not "null;".

Properties

All public properties should be documented.

Try to minimize access privileges; just because other classes need to see the value
of a property doesn't mean the property has to be public. Use "public-read" on these
variables. Even if they need to be written outside the class, note that you can
tack a second access modifier on it for writes, so you can for example have "public-read protected"
which means everybody can read and subclasses can write this property.

Similarly, use public-init as much as possible on all properties that are only settable at
construction time.

Variables

Prefer "def" over "var" as much as possible. Unlike Java's "final" which was extra typing, def lets
you create a final variable.

def newFile = new File(file, "NewFolder");
newFile.mkdir();

Constants created as a def inside a method can be formatted like other variables - in other words,
like newFile above instead of NEW_FILE.

Null Checks

JavaFX performs null checks for you in a form of short-circuit evaluation, so there is no need to
sprinkle them all over your code.

// Bad
if (foo != null && foo.bar != null) {
    x = foo.bar.baz;
}
// Good
x = foo.bar.baz;

Note in particular that nulls are ignored when it creates sequences.

Thus, rather than something like this:

if (header != null) {
    content = [ background, footer, header ]
} else {
    content = [ background, footer ]
}

you should simply write this:

content = [ background, footer, header ]

These two code snippets are equivalent but the second style is clearly preferable.

Ternary Expressions

JavaFX doesn't have the ?: operator from Java, but it lets you use if-else as expressions.
Therefore, you can do this:

var foo = if (bar) 3 else 4

Code should be using the above construct, preferably without extra { }'s and "then", to keep things
simple, instead of more convoluted logic to handle conditional initialization of variables,
objects, or function arguments.

Similarly, you should use generator expressions instead of for loops with sequence inserts.

// BAD
var seq: String[] = [];
for (name in names) {
    insert name into seq;
}

// GOOD
seq = for (name in names) name

The "override" modifier

The "override" keyword should appear after the access modifier, it should not be before it as the @Override annotation often is in Java:

public override function yes() { } // YES
override public function no() { } // NO

Discussion and Justification:

(This is where I provide more justification or discussion around recommendations listed above.)

Type Declarations

There is a lot of variation in how type declarations, and object literal key value pairs, are formatted:

var foo: Integer;  // 1
var bar : Integer; // 2
var baz:Integer;   // 3

In this style guide I have recommended the first approach. This is a bit arbitrary, but my reasoning is as follows:

This seems to be the convention in Scala, which also defines types after variables, and Scala's formatting seems to
continue the general style of Java so mixing and matching conventions seems like a good idea.
Using no spaces (as in #3 above) is in my opinion less readable since the whole item appears as a single unit

Specify Return Types

At first I relied on the language support for automatically figuring out return types. It's really nice when you're
just writing functions that you're using locally. But I ran into problems once I started writing more code,
and started overriding functions in my class hierarchy. For example, in many cases I have a function which in
my mind is a "void" function - because I don't care about the return value and I didn't explicitly return anything.
However, if the last expression evaluates to a number, your function signature now returns a number, and if you in
a subclass try to override this method with another "void" function, you get an error if you don't also happen
to have a last expression in your function that evaluates to the same type! This also doesn't just happen with void;
in other cases the type inference may conclude that the return type should be "Integer", whereas in your mind you
intended for the function to return a "Number", and if your subclass now tries to return a Number you get either
a compilation or a truncation error.

Override Modifier

The recommendation to put override after public is based on current usage. A quick search of the JavaFX SDK codebase
showed that 80% of all combinations of public and override are of the public override form.

Version 1, November 8th 2009.
Tor Norbye, tor.norbye@sun.com
http://blogs.sun.com/tor

Home

Coding Conventions for the JavaFX Language

Introduction

Default: Stay Consistent with Java

File organization

Type Definitions

Object Literals

Function Returns

Properties

Variables

Null Checks

Ternary Expressions

The "override" modifier

Discussion and Justification:

Type Declarations

Specify Return Types

Override Modifier

Labels

Comments (5)

dnarmitage says:

Ternary Expressions

Braces generally

dnarmitage says:

tnorbye says:

dnarmitage says:

SEMorris says: