Code Style

This document is intended as a guide and not a rule.

Whitespace

Indentation should be four spaces, not tabs.

Add one space after operator, before and after binary operators (x + y).

Never add whitespace before a semicolon.

Never add whitespace before the opening ( in a function call.

Never add whitespace before type attributes (func<null>).

Add exactly one space after the opening colon in a tuple literal: [: foo, bar]

All commas should be followed by exactly one space (foo(x, y, z)). The exception to this rule is for sequences that span multiple lines. In this case, each element of a sequence should be on its own line with the comma at the end of the line.

Files should end with exactly one line break.

Curly Braces

Opening curly braces should be on the same line as the declaration that opens them (BSD KNF style).

Parentheses

Developers are encouraged to use the fewest number of parentheses required. Use operator precedence to your advantage.

Comments

Comments on the same line as code should be prefixed with two spaces:

foo();  # Two spaces go before a comment.

Comments that explain "why" should be full sentences and end with a period.

Comments that explain "what" should prefer full sentences with a period, but may be sentence fragments with no punctuation.

"TODO" comments (or otherwise) should be written as #@ TODO(name): Todo comment here. The @ denotes a special one-off comment. If the comment spans multiple lines, it should be written as follows:

#@ TODO(basta): This is a special TODO comment that
#@ spans multiple lines.

There should be one space after the @ symbol. After trimming the #@ from a special comment, any leading whitespace that remains is considered part of the comment. If there is no leading whitespace, the contents of the special comment will treat the line break as a space (that spans rather than that\nspans, in the example above). A line within a special comment containing only #@ with no trailing space is considered a paragraph break in the comment (two line breaks).

#@ TODO(basta): This is a special comment.
#@
#@ It spans
#@ multiple lines.
#@
#@     This is indented.
#@
#@ This is a new paragraph.

becomes

TODO(basta): This is a special comment.

It spans multiple lines.

    This is indented.

This is a new paragraph.

Tools should expect special comments to use this format. Types of comments that tools should recognize are:

• TODO: indicates unimplemented concepts or incomplete code that needs revisiting.
• NOTE: indicates special considerations
• FIXME: indicates a bug
• OPT: indicates an optimization or request for optimization
• BUG: indicates a bug. The body of the comment should contain a ticket number or URL to the reported issue. #@ BUG(basta): Workaround for a bug in Firefox (http://bugzil.la/35168)

Variables

Declarations should prefer the var x syntax. Typed declarations should be used to minimize confusion and help explain a piece of code.

var x = foo('x');
var y = foo('y');
var z = foo('z');
var a = bar('a');
var b = bar('b');
var c = bar('c');

# vs

float:x = foo('x');
float:y = foo('y');
float:z = foo('z');
int:a = bar('a');
int:b = bar('b');
int:c = bar('c');

Variables whose values should never be modified should use the const keyword.

Symbols

Symbols (names) should always be written in camelCase, except for class names which should be written in PascalCase.

Always compare variables to values rather than the other way around. That is, x > 4 is preferred to 4 < x.