Developer Guide

nodeGame Developer Guide

Installation

1. Download the latest version of node.js for your platform.
2. Download the latest version of git for your platform.
3. Get the latest development source code from GitHub for [Mac/Linux] (https://raw.githubusercontent.com/nodeGame/nodegame/master/bin/install.latest.sh) or for [Windows] (https://raw.githubusercontent.com/nodeGame/nodegame/master/bin/install.latest.cmd).

Compiling the Code

If you make changes in the code, you will have to run the build scripts to update the files necessary for running nodeGame:

1. Do your changes in the module of your choice.
2. In that module: node bin/make.js build -a
3. Go to the server module (nodegame/node_modules/nodegame-server) and type: node bin/make.js build-client -a -o nodegame-full

Building documentation

After changing code and especially documentation comments for a module, it is recommended to re-build the HTML documentation with node bin/make.js doc.

Browse Sources

• Client
• Widgets
• Window
• Server

Writing Code

The source code of nodeGame follows the following conventions.

Whitespace

• Indenting uses four spaces, tabs are never used.
• Lines do not have any trailing whitespace.
• Source files have one newline at the end.
• In control flow statements, the opening parenthesis follows a space (see examples in Braces).
• There is no space between a function name and the opening parenthesis of its parameters.

Braces

• Opening braces are on the same line as their corresponding control flow statements.
• Closing braces are on their own line.
• When a control flow statement is broken into multiple lines, it is followed by an empty line.
• Braces may only be left out if the single statement it would contain is on the same line as the leading control flow statement (see bottom of example).

Examples:

function control(a, b) {  // No space after 'control'.
    if (a >= b) {
        console.log('Greater or equal');
    }
    else if (a < b) {  // Note brace arrangement around 'else'.
        console.log('Less');
    }
    else {
        console.log('NaN');
    }

    while (veryLongCondition1 &&
           veryLongCondition2) {  // Empty line following.

        doThing(function(e) {   // No space after 'function'.
            console.log(e);
        });
    }
}

if (x < 0) x = 0;  // OK

if (x === 5) {
  x = 8;  // OK
}

if (x > 9)
    x = 9;  // NOT OK!

Logic

• Strict in-/equality !==/=== is used instead of !=/== wherever possible.
• All "for-in" loops check hasOwnProperty on each iteration.
• Variable shadowing should be avoided.

Examples:

function printProps(obj) {
    var i;

    for (i in obj) {
        if (obj.hasOwnProperty(i)) {  // Important.
            console.log(i, obj[i] === null ? 'N/A' : obj[i]);
        }
    }

    function() {
        var obj;  // Shadowing NOT OK!
    }();
}

Naming

• Variable names use camelCase.
• Constant names use UNDERSCORED_UPPER_CASE.
• Class names use PascalCase.
• Names should be descriptive.

Miscellaneous

• Lines are at most 80 characters long.
• Strings use single quotes by default, double quotes if more convenient.
• All variables are declared at the top of their scope and are assigned to separately.
• Messages in new exceptions start with the class name suffixed with a dot (if inside a class), followed by the function name and a colon. The description starts with a lower-case letter and ends with a period.
• Comments are generally on lines of their own, before the code they concern, starting with a capital letter and ending with a punctuation symbol, usually a period.

Examples:

function sumArray(array) {
    var i, sum;  // All declarations on top, no assignments.

    // Check input.
    if (!array || 'number' !== typeof array.length) {
        throw new TypeError('sumArray: array.length must be number.');
    }

    // Sum up elements.
    sum = 0;
    for (i = 0; i < array.length; ++i) {
        sum += array[i];
    }

    console.log("Sum of 'array': " + sum + '.');
    return sum;
}

MyClass.prototype.fail = function() {
    throw new Error('MyClass.fail: always throws.');
}

Writing Documentation

nodeGame uses docker to generate its documentation. In addition to the above practices used in the code, the following rules apply for doc comments.

For an example of these rules used in practice, see the documentation of nodegame-server.

Sections

Docker pages use a hierarchy of sections, with different levels denoted by #, ##, ### etc. A nodeGame source file has the following structure:

# ClassName [filename without extension]
## ClassName constructor
### ClassName.field
### ...
## ClassName methods
### ClassName.method
### ...

For example:

# Circle
## Circle constructor
### Circle.posX
### Circle.posY
### Circle.radius
## Circle methods
### Circle.setPosition
### Circle.getArea
### Circle.draw

In special cases, more sections can be added.

Documentation comments

After the section definition, the rest of the doc comment describes the documented field or method.

• The first line is a short summary, beginning with a capital letter and ending without a period, surrounded by empty lines. For methods, this should start with a verb in third person.
• Next, an optional longer description follows. The sentences in the descriptions end in a punctuation symbol.

Field example:

/**
 * ### Circle.radius
 *
 * Radius of the circle
 *
 * The radius is half the diameter.
 */
this.radius = radius;

For methods:

• Parameter descriptions start with a capital letter, the last sentence has no period.
• Descriptions of optional parameters begin with "Optional.".
• @param, @return sections that span multiple lines have the extra lines indented by two spaces.
• There is a blank line before @return sections.

Method example:

/**
 * ### Circle.setPosition
 *
 * Sets the circle's position
 *
 * @param {number} x The new x position
 * @param {number} y The new y position
 * @param {boolean} rel Optional. Whether to add to the old position
 *   instead of using absolute coordinates. Default: FALSE
 *
 * @return {boolean} TRUE on success, FALSE on failure
 */
Circle.prototype.setPosition = function(x, y, rel) { ... }

• Horizontal lines (---) are never used.

Bulleted lists

• All bulleted lists in documentation comments are surrounded by empty lines.
• Lists in @param and @return are indented by two spaces.

Example:

/**
 * ### Circle.draw
 *
 * Draws the circle
 *
 * Can draw to either:
 *
 * - The console
 * - An HTML canvas
 *
 * @param {object} options Drawing options with the following fields:
 *
 *   - target (string): Where to draw
 *   - color (string): Optional. Color with which to draw
 *
 * @return {object} An object containing the results with the
 *   following fields:
 *
 *   - success (boolean): Whether the drawing was successful
 */
Circle.prototype.draw = function(options) { ... }