Coding Conventions For JavaFX Script

With so many people developing applications using JavaFX Script recently it is time to look at some coding conventions. These conventions will include coding standards and best practices. Below I will establish coding conventions that are applicable to JavaFX Script, many of these will come from Java's coding conventions. Remember that what I am about to mention acts as a guide and should be followed where it is applicable.

Naming

Variable and function names should be in camel case (eg isInitialized). Constant names should be in upper case with each word separated by an underscore (eg TIMER_DURATION). Class and Mixin names should be in title case (eg AppUtils). Do note that in JavaFX Script both variables/constants and functions all share the same namespace, therefore you need to name carefully.


Ordering

In a JavaFX Script source file (.fx) the following should be ordered as follows:

1. Source file documentation
   
2. Class/mixin documentation
   
3. Class/mixin
4. Class/mixin constants
5. Class/mixin variables
6. Class/mixin initialisation blocks (init then postinit)
7. Class/Mixin functions

Functions should be ordered by functionality, eg:

function func1(arg1)
{
}

function func1(arg1, arg2)
{
}

function func1(arg1, arg2, arg3)
{
}

function func2()
{
}

When defining a multiple functions of the same name ensure that the function arguments are in exactly the same order in to avoid confusion (see the example above).


Indentation

In general 4 spaces should be used for indenting code. Avoid using lines that are longer than 80 characters, wrap up long lines instead, eg:

function aFunction(argument1, argument2, argument3,
    argument4)
{
}

Long lines can be wrapped by the comma, open perenthesis characters.


Documentation

Preferably all public parts of the API should be documented since other people may use the API in their code. Only comment parts of the code that are not clear from reading it. Where ever possible use clear naming for classes, mixins, functions, variables and constants that indicate exactly what it does. This will help cut down on comments which can quickly go out of date through major code changes. Only include useful information in the comments that make it clear what a piece of code does, and why it is done that way. When handling exceptions that are going to be ignored always including a comment about why it is to be ignored.

Place comments just above the code being documented, not at the right hand side of the code, eg:

// Duration in seconds.
def DURATION;

Declarations

Place no more than one statement per line (this also apples to variable and constant declarations). Variable and constant declarations should only be placed at the beginning of a function, init, postinit, and class/mixin block. Do not declare variables and constants when they are first used (it can confuse people) like this:

if(arg1 > arg2)
{
    var temp;

    temp = arg1;
}

It is good practice to initialise variables when they are declared in order to make it clear what starting value or reference they have.


White Space

Each declared variable, constant, function should be on their own line, and two blank lines should separate variables/contants and blocks/functions, eg:

class aClass
{
    def const1;
    def const2;
    var var1;
    var var2;
   

    init
    {
    }

    postinit
    {
    }

    function func1()
    {
    }

    function func2()
    {
    }
}

Use two blank lines to separate class/mixin definitions in the source file. Each operator that is used needs to be surrounded by a space, eg:

minutes = seconds * 60;

Scoping

Keep internal class/mixin variables and constants private by omitting a scoping keyword unless there is a good reason to expose them externally. If a variable is to be read but not changed externally then use the public-read keyword, else if a variable is only allowed to be set once externally during object creation then use the public-init keyword. If a class/mixin variable or constant is meant to be accessed by sub classes/mixins then use the protected keyword.


Best Practices

• Try to keep recusion in each function to no more than 3 in order to make it simple to understand and maintain
  
• Try to keep nesting to no more than 3 levels with each object literal in order to make it clear what the sequential order is
• Do use variables to reduce object literal nesting by having object literals refer to them instead of embedding an object literal
  
• Avoid using names for variables, constants, functions and classes/mixins that are reserved by JavaFX Script if at all possible
• Minimise the use of binding since it can degrade performance in an application
• Use binding where a variable's value has to be constantly kept in sync with another variable since it reduces unessesary boilerplate code
• Use perenthesis to clarify the operating order for an expression (eg if((a == b) and (c == d)))
• Only use a single return statement (which is the last line) in a function, this makes a function easy to follow in sequential order