xJSFL coding conventions

Categories:Coding

Code

Layout

Related lines of code should be grouped into blocks

Whatespace should be used to separate discrete units of functionality, and help make processes clear

Strongly consider commenting each block with leading single-line comments

Declarations should be lined up in columns. See the section on declarations below.

// parameters
    a			= a || 1;
    b			= b || 2;

// variables
    var c		= 3;
    var d		= 4;

// process
    if(a > b)
	{
		return a + b + c + d;
	}

Tabs

xJSFL's tab width is 4 spaces, expressed as a single tab character (which may not show here, depending on your browser):

'0 tabs in'
	'1 tab in'
		'2 tabs in'

Operators

Operators should generally be surrounded by whitespace:

var value = (a + b) * (c - d);

The exception to this is string concatenation, where cuddled + operators around variables can make it easier to read:

var message = 'The product of (' +a+ ' + ' +b+ ') * (' +c+ ' - ' +d+ ') is ' +value;           // easier to read
var message = 'The product of (' + a + ' + ' + b + ') * (' + c + ' - ' + d + ') is ' + value;  // harder to read

In cases with many values to concatenate, consider using String.inject():

var message = 'The product of ({a} + {b}) * ({c} - {d}) is {value}'.inject(a, b, c, d, value); // easiest to read

Braces

Braces should never be cuddled, and start and end braces should line up vertically:

function test(state)
{
	if(state)
	{
		var obj =
		{
			a:1,
			b:2,
			c:3
		}
	}
}

Quotes

Single quotes should be used in preference over double quotes:

var name = 'Bill';

The exception is when escaping single-quotes would become unreadable, then double quotes are fine:

var message = 'The dialog\'s members haven\'t been initialized';  // no so good
var message = "The dialog's members haven't been initialized";    // better, as more readable

Comments

Inline comments should be outdented by a single tab, making it easy to scan the code:

// this is block 1
    if(something)
    {
        doSomething(something);
    }
// this is block 2 if(somethingElse) { doSomethingElse(somethingElse); }

Block level comments should line up with the start of the declaration:

/**
 * A test function that does something useful
 * @param	{Number}	a	The a parameter
 * @param	{Number}	b	The b parameter
 * @param	{Number}	c	The c parameter
 */
Test = function(a, b, c)
{
	this.a = a;
	this.b = b;
	this.c = c;
}

Declarations

Variables names and values should be lined up in columns using tabs when more than one variable is being set, with the = operator ranged right, with a single space separating it from the assignment:

var name			= 'Something';
var muchLongerName	= 'Something else';

Note: In Komodo, you can hold down ALT and drag the mouse vertically to insert the cursor into multiple lines at once, making it easy to tab or un-tab blocks of text.

If only one variable is being set, it is OK to use a single space either side of the = operator

if(state)
{
	var name = 'Something';
}

If declaring object properties, endeavour to place them in columns:

var obj = 
{
	value:		1,
	property:	'blur',
	date:		new Date()
}

If declaring multiple blocks of variables or properties, endeavour to makes sure they all line up, even if the columns of one block are shorter than the other:

var foo = 
{
	a:		1,
	b:		2,
	c:		3
}

var bar = 
{
	one:	1,
	two:	2,
	three:	3
}
Colons may be lined cuddled with their object name, or lined up by the value, as long as the style is uniform within the file:
// file 1
var foo = 
{
	a:		1,
	b:		2,
	c:		3
}
// file 2
var bar = 
{
	one		: 1,
	two		: 2,
	three	: 3
}

Variable naming

Variables should always be camelCase:

var value			= 1;
var anotherValue	= 2;

If a variable name contains an acronym, it should be in upper case only when used after the first word:

var uri				= 'file:///c|/temp/';
var flashURI		= fl.configURI;
var someOtherURI	= xjsfl.uri;

Class constructors should always be capitalised CamelCase, and the class declaration should come before the function keyword (this is actually a technical constraint of the SpiderMonkey JavaScript engine):

Test = function()
{
	// constructor code
}

var test = new Test();

Constants should be capitalised underscore_case:

var SOME_VALUE = 10;

Files

Encoding

JSFL files should be encoded as UTF-8 with a BOM, as your files may be used on Japanese or Chinese machines if distributed.

File naming

"Natural language" filenames should be favoured over "camelCased" or "hyphenated-file-naming"

animation tools.jsfl

File names should generally be "lower case":

/config
	/animation tools.xml
/jsfl
	/functions.jsfl
	/globals.jsfl
	/settings.jsfl

Class files only should be named after the class, in "CapitalizedCamelCase" (this makes it simpler to work out file finding in class loads):

/jsfl
	/libraries
		/AnimationTools.jsfl
		/ExportTools.jsfl

Module root folders should be "Title Case":

/xJSFL
	/modules
		/Animation Tools
			/config
			/jsfl
			/ui

Any files whose names appear directly in the Flash UI (i.e. SWF panels and Snippets) should be "Title Case" or "Sentence case":

/flash
	/WindowSWF
		/Animation Tools.swf
/jsfl
	/Snippets
		/Development
			/Export AS3 class definitions

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>