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,
http://javascript.crockford.com/code.html.
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.
Indentation
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.
Comments
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:
PHP Code:
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.
PHP Code:
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
- There should be no space between the name of a function and the ( of its parameter list.
- There should be one space between the ) and the { that begins the statement body.
- The body itself is indented two spaces.
- The } is aligned with the line containing the beginning of the declaration of the function.
PHP Code:
function doAwesome(a, b) {
temp.x = 1;
return(temp.x+1);
}
Never use an inner function because it is not scoped and can be accessed outside of the outer function, for example:
PHP Code:
function outer() {
function inner() {
return(123);
}
outer2();
}
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.
If you are declaring an anonymous function (closure), there should be one 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.
PHP Code:
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
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.
- Variables and functions should start with a lower case letter.
- Constants should be all upper case.
- Classes should start with an upper case letter
Statements
Simple Statements
Each line should contain at most one 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
{ }.
- The enclosed statements should be indented two more spaces.
- The { should be at the end of the line that begins the compound statement.
- The } should begin a line and be indented to align with the beginning of the line containing the matching {.
- Braces should be used around all statements, even single statements, when they are part of a control structure, such as an if or for statement. This makes it easier to add statements without accidentally introducing bugs.
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:
PHP Code:
if (condition) {
statements
}
if (condition) {
statements
} else {
statements
}
if (condition) {
statements
} else if (condition) {
statements
} else {
statements
}
for Statement
A
for class of statements should have the following form:
PHP Code:
for (initialization; condition; update) {
statements
}
for (variable : array) {
if (filter) {
statements
}
}
The first form should be used with loops of a predeterminable number of iterations.
while Statement
A
while statement should have the following form:
PHP Code:
while (condition) {
statements
}
do Statement
A
do statement should have the following form:
PHP Code:
do {
statements
} while (condition);
Unlike the other compound statements, the do statement always ends with a
;.
switch Statement
A
switch statement should have the following form:
PHP Code:
switch (expression) {
case expression:
statements
default:
statements
}
Each
case is aligned with the
switch. This avoids over-indentation.
Each group of statements (except the
default) should end with
break or
return.
Do not fall through.
Whitespace
Blank lines improve readability by setting off sections of code that are logically related.
Blank spaces should be used in the following circumstances:
- A keyword followed by ( should be separated by a space.
- Each ; in the control part of a for statement should be followed with a space.
- Whitespace should follow every ,
Bonus Suggestions
{}:
Use
{} instead of
new[0]:
PHP Code:
temp.someArray = {};
This keeps thing clear by avoiding using a constructor-specific syntax for creating a data structure.
==:
Always use
== instead of
= when comparing variables:
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:
PHP Code:
total = subtotal + +myInput.value;
is better written as:
PHP Code:
total = subtotal + (+myInput.value);
so that the
+ + is not misread as
++.
07-07-2009, 07:26 AM
I guess it's in the Advice thread somewhere.
Linear Mode
