GraalScript2 (GS2) Coding Conventions

This is a set of coding conventions and rules for use in GS2 programming. It is an adaptation of Crockford's document,

Over a script's lifetime, it will be handled by many people, making it very important to clearly communicate its structure and characteristics, making it less likely to break when modified in the never-too-distant future.


The unit of indentation is 2 spaces. The code editor in Remote Control (RC) already handles this by changing a tab-stop to 2 spaces automatically.

Line Length

Avoid lines longer than 80 characters. If a statement won't fit on a single line, it may be better to break it up. Place the break after an operator, ideally after a comma. The next line should be indented 4 spaces.


Be generous with comments. It is useful to leave information that explains how your script works for others (possibly yourself) who will need to understand what you have done.

The comments should be well-written and clear, just like the code they are explaining. Occasional humor might be appreciated as well. Frustrations will not.

It is important comments be kept up-to-date. Incorrect comments can make programs harder to read and understand.

Make comments meaningful. Focus on what is not immediately visible. Don't waste the reader's time with stuff like:
i = 0; // Set i to zero. 

Generally use line comments. Save block comments for formal documentation and for commenting out.

Variable Declarations

Variables should be declared before used. GS2 does not require this, but doing so makes the program easier to read.

The variable declarations should be the first statements in the function body.

It is preferred that each variable be given its own line and comment:
temp.currentEntry; // currently selected table entry
temp.level; // current level
temp.size; // size of table 

Avoid using global variables. Variables that don't need to be accessed outside of the function should always have a temp. preceding them.

Always use the prefix even after originally declaring the variable for clarity.

Function Declarations

function doAwesome(a, b) {
  temp.x = 1;
  return temp.x+1;

Inner Functions

Never use an inner function because it is not scoped and can be accessed outside of the outer function, for example:
function outer() {
  function inner() {
	return 123;

function outer2() {
  echo (inner()); // echos 123

Using an inner function like that just makes things confusing in terms of scope, because it actually becomes a global function.

Anonymous Functions

If you are declaring an anonymous function, there should be 1 space between the word function and the (.
If the space is left out, then it may seem that the function's name is "function", which is incorrect.

temp.distance = function (x1, y1, x2, y2) {
  return ((x2 - x1)^2 + (y2 - y1)^2)^.5;
echo (temp.distance(2, 2, 1, 1)); 

Anonymous functions can unfortunately not be executed in the same statement they are declared in.


Names should be formed from the 26 upper and lower case letters (A .. Z, a .. z) and the 10 digits (0 .. 9) and _.
Avoid other characters.

Do not use _ as the first character of a name. It is sometimes used to indicate privacy, but it does not actually provide privacy. Avoid conventions that demonstrate a lack of competence.


Simple Statements

Each line should contain at most 1 statement. Put a ; at the end of every simple statement.
Note that when declaring a variable as a function, it is still an assignment statement and must end with a semicolon.

Compound Statements

These are statements that contain lists of statements enclosed in { }.

return Statement

return is a statement, not a function, therefore it should not use ( ) around the value.

if Statement

The if class of statements should have the following form:
if (condition) {

if (condition) {
} else {

if (condition) {
} else if (condition) {
} else {

for Statement

A for class of statements should have the following form:
for (initialization; condition; update) {

for (variable : array) {
  if (filter) {

The first form should be used with loops of a predeterminable number of iterations.

while Statement

A while statement should have the following form:
while (condition) {

do Statement

A do statement should have the following form:
do {
} while (condition); 

Unlike the other compound statements, the do statement always ends with a ;.

switch Statement

A switch statement should have the following form:
switch (expression) {
case expression:

Each case is aligned with the switch. This avoids over-indentation, but maintains the pattern of indenting all groups of statements.

Each group of statements (except the default) should end with break or return. Do not fall through.


Blank lines improve readability by separating sections of code that are logically related.

Blank spaces should be used in the following circumstances:

Bonus Suggestions


Use {} instead of new[0], for example:
temp.someArray = {}; 

This keeps thing clear by avoiding using a constructor-specific syntax for creating a simple data structure.


Always use == instead of = when comparing variables, for example:
if (a == b) { 

Confusing Pluses and Minuses

Be careful to not follow a + with + or ++. This pattern can be confusing. Insert parenthesis between them to make your intention clear. = temp.subtotal + +temp.value; 

is better written as: = temp.subtotal + (+temp.value); 

so that the + + is not misread as ++.

Code Placement

It is generally a bad idea to put code outside of an event block, unless you are joining another class. = "Hello";
function onCreated() {

is better written as:
function onCreated() {
  setimg("door.png"); = "Hello";

There are 6 comments on this page. [Display comments]

Valid XHTML 1.0 Transitional :: Valid CSS :: Powered by WikkaWiki