ActionScript Coding Style Conventions

This document lays out the coding standards used by LongTail Video in writing ActionScript code. These conventions are in place to encourage source code that is consistent, readable, and well-organized.

If you are searching for a convention for something not covered by this document, first consult the Flex SDK coding conventions and best practices, then Code Conventions for the Java Programming Language.

Line Breaks, Indentation, and White Space

Line length

All lines should break before 119 characters.

Suggested breakpoints

It is best to break after a comma or before an operator.

Examples

bar(myVar1,
	myVar2,
	myVar3);

foo((myVar1 == myBar)
	|| (myVar2 == myBar));

Line wrap alignment

When breaking lines, align the new line with the beginning of the expression at the same level on the previous line. If you are breaking in the middle of a statement, always align the new line one level in from the beginning of the statement.

Line wrapping on Boolean operations

Wrapping on Boolean operations with three or less comparisons and line length less than 119 characters is at the discretion of the author. For operations with more than three comparisons, it is recommended that the author create a function which returns a Boolean value.

Indentation

Indentation should be done via tabs, rather than spaces. For line wrapping purposes, a tab is equivalent to four spaces.

Operator whitespace

Operators (http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/operators.html) should always be surrounded by whitespace. For example,

trace(2 + 3);

or

var foo:String = "Hello World";

Keyword whitespace

Keywords (http://livedocs.adobe.com/flex/201/langref/statements.html) should always be followed by a space, unless the line breaks after the keyword. For example,

while (condition) {
	operations;
}

Comments

Documentation comments

Documentation comments should be used before all class and method declarations. These comments are automatically processed by ASDoc (http://livedocs.adobe.com/flex/201/html/wwhelp/wwhimpl/common/html/wwhelp.htm?context = LiveDocs_Book_Parts&file = asdoc_127_1.html). They should assume the following form:

/**
 * This is the documentation for a class or function.
 *
 * @tag Tag Text
 */

Class header files should contain SVN auto-replace directives of the following form:

SVN: $Id$

Block comments

Block comments should be used to describe variables, methods, data-structures, and algorithms. They can be used within classes and methods, but they should always proceed what they are describing, and should be indented as such. Block comments assume the following form:

/*
 * This is a block comment.
 */

Single line comments

Single line comments can be used anywhere that block comments are appropriate, but where no line break is necessary. Single line comments assume the following form:

/* This is a single line comment. */

=== Trailing comments ==== Very short comments may appear on the same line of code they describe, but should be indented to distinguish them from the code itself. Trailing comments assume the following form:

var temp:String;		// Need a temp variable

Profanity and All-Caps

The use of profanity and all-caps is vigorously discouraged. The authors recognize that there is sometimes no alternative.

Declarations

Variable declarations

All variables should be declared on their own line, and should have a type. The form

var i:Number = 0;
var j:Number = 0;

is greatly preferred to

var i, j = 0;

Function declarations

The purpose of declaring a function is to encapsulate a specific operation. To that end, functions must

• have documentation that describes the function's purpose, input, and output.
• have a scope (public, private, protected).
• have a name that accurately describes the operation being performed.
• have a return type.
• be intuitive in its operation. If you believe that someone else would have difficulty understanding the operation of the function without your help, consider refactoring. If the function is necessarily complex, document it exceptionally well.
• not exceed 15 lines in length. If a function is longer than this, split it up into several functions.

The use of semi-colons at the end of function declarations is prohibited.

Statements

Statement separator

All statements should be terminated with a semi-colon. For example, var foo:String = "Hello World";

If… else statements

If… else statements should be formatted

• with a space after the "if" and "else" keywords
• with an opening brace on the same line as the conditional statement
• with the operations on the line after the opening brace
• with a closing brace on the line after and the final operation

For example,

if (condition) {
	operations;
} else if (condition) {
	operations;
} else {
	operations;
}

While loops

While loops should be formatted

• with a space after the "while" keyword
• with an opening brace on the same line as loop parameters
• with the operations on the line after the opening brace
• with a closing brace on the line after and the final operation

For example,

while (condition) {
	operations;
}

For loops

For loops should be formatted

• with a space after the "for" keyword
• with spaces between operators
• with spaces after the semi-colons
• with an opening brace on the same line as loop parameters
• with the operations on the line after the opening brace
• with a closing brace on the line after and the final operation

For example,

for (int i = 0; i < loops; i++) {
	operations;
}

Ternary Statements

Use ternary statements for simple comparisons and null checks. The following is allowed:

return j ? j.toString() : "";

However, do not use ternary statements for complex Boolean comparisons, or use nested ternary statements. The following is discouraged:

foo = (x > y && x > z) ? x : ( (y > z) ? y : z);