JavaFX Script Coding Conventions for JFXtras

Good code conventions are not dictated, but instead evolve out of language best practices. Since JavaFX is a new language, there is a wide variation in coding styles; however, in the major codebases and blogs it is easy to see common patterns emerging. In particular, Tor Norbye, has published a very good coding conventions document. Between his document and this one, you should find answers to any questions you have about the conventions used in JFXtras.

Guiding Principles

Maintainability. Code is written once, but read and maintained hundreds of times. This makes it important that care is not only given to making new code easy to write, but also easy to understand years into the future.

Succinctness. The JavaFX language affords many opportunities to reduce the verbosity of your code, and where it does not sacrifice readability, fewer lines and fewer characters are better.

Java Compatibility. It is very common to use both JavaFX Script and Java in the same program, so reducing the impedance mismatch between the two is important. Therefore, consistency with the established Java Code Convention is highly desirable.

File Names and Packaging

JavaFX files should be placed in folders by their package structure and in a file matching the public class name.

Import Statements

Import statements should appear at the top of the file right after the package statement. Class imports are preferred to star (*) imports for a small number of classes (5 or less). Unused imports should be removed whenever possible.

Variable Naming

Naming should follow the conventions used in the core JavaFX API classes. Variable and function names should be in camel case (e.g. isInitialized, valueOf, onResponseCode). Constant names should be in upper case with each word separated by an underscore (e.g. PI, TIMER_DURATION, MAX_VALUE). Class and Mixin names should be in title case (e.g. Resizable, HttpRequest).

Variable, function, and class names should be descriptive without being overly verbose. Local variables used only for temporary storage or counters can have shorter names.

Indention

Four spaces should be used to indent code. Tabs may be used as long as the code editor is set to replace tabs with spaces when the file is saved. Lines should be wrapped at 120 characters. Preferably the wrap will occur after a comma or an operator.

Brace Placement

Opening square braces and curly braces should always be placed on the same line as the code they are associated with. Closing braces should be either on the same line as the opening brace or on a new line by them selves and indented to the appropriate level.

Timeline {
    repeatCount: Timeline.INDEFINITE
    keyFrames: [
      at (0s) { xPosition => 0 }
      at (3s) { xPosition => 200 tween Interpolator.LINEAR }
    ]
}

Declarations

Variable and function declarations should take full advantage of type inference whenever possible. The on replace keywords should be kept on the same line as the declaration when possible.

def DEFAULT_BACKGROUND = Color.GRAY;

var background: Rectangle;
var rowCount = 0;

var listOffset = 0 on replace {
    var asInt = listOffset as Integer;
    if (asInt != listOffsetInt) {
        listOffsetInt = asInt;
    }
}

Comments

Public variables and functions should be commented using javafxdoc comment blocks. Comments within the code should be used sparingly. Rather than writing a comment, try using clear names for variables or refactoring functionality into well named functions. If a function does appear in the code, it should be above the line and not to the right of the line.

/**
* The size of the border that will be placed around this Grid.  The border
* is both empty and transparent.  Set this to 0 to remove the border.
*/
public var border:Number = 3 on replace {
    requestLayout();
}

// Use a stable update so toFront and toBack work correctly.
content = SequenceUtil.stableUpdate(content, newContent) as Node[];

White Space

White space should be used where necessary to make the code more clear. There should be a space after keywords such as if, for, and at.

    var newContent = for (row in rows) {
        row.cells
    }

    if (not node.focused) {
        node.requestFocus();
    }

    var rowTotal = vgap * (rowActual.size() - 1) + border * 2;

Special Considerations for Sequences

Members of a sequence should always be separated by either a comma or curly braces. This prevents ambiguites such as [1 3 -5] which is [ 1, -2 ] rather than [ 1, 3, -5 ].

var evens = [ 2, 4, 6, 8, 10 ];

Scene {
    contents: [
        Rectangle {
            width: 100
            height: 200
        }
        Circle {
            Radius: 50
        }
    ]
}

Anatomy of a Source File

The sections of a JavaFX Script source file should be generally ordered in the following manner:

1. Copyright and license comment block
2. Package and import statements
3. Class/mixin comment block (including @profile)
4. Class/mixin declaration
5. Class/mixin constants
6. Class/mixin variables
7. Class/mixin initialisation blocks (init then postinit)
8. Class/Mixin functions

/*
* Copyright (c) 2008-2009, JFXtras Group
* All rights reserved.
*
* …BSD license text…
*/
package org.jfxtras.scene.example;

import javafx.scene.Node;
import org.jfxtras.scene.ResizableCustomNode;

/**
* This is a pretend node used as an example.
*
* @author Stephen Chin
* @author Dean Iverson
* @profile desktop
*/
public class PretendNode extends CustomNode {

    /**
* The amount of horizontal space between each child node.
*/
    public var spacing:Number;

    /**
* A sequence of child Nodes that will be rendered in order.
*/
    public var content:Node[];

    init {
        if (not isInitialized(layoutInfo)) {
            layoutInfo = LayoutInfo {
                hpos: bind hpos
                vpos: bind vpos
            }
        }
    }

    override function create() {
        Grid {
            border: 0
            hgap: bind spacing
            nodeVPos: bind nodeVPos
            rows: bind Row {
                cells: content
            }
        }
    }
}

Function Order

Functions should be grouped by functionality and overloaded functions should keep their arguments in the same order.

public function drawShape( x: Number, y: Number ) {
}
public function drawShape( x: Number, y: Number, width: Number, height: Number ) {
}
public function resize( width: Number, height: Number) {
}