Coding Conventions - adobe-photoshop/spaces-design GitHub Wiki

Prototypical inheritance pattern:

function MyClass() { // constructor
    Parent.call(this); // if this is a subclass
    // ...
}

// the following are only necessary if this is a subclass
MyClass.super_ = Parent;
MyClass.prototype = Object.create(Parent.prototype);
MyClass.prototype.constructor = MyClass;

// or, even better:
var inherits = require("adapter/util").inherits;
inherits(MyClass, Parent);

/**
 * Declare instance variables so we can JSDoc them.
 * @type {string}
 */
MyClass.prototype.myVar = null;

/**
 * @override
 * For override methods, use this pattern for super calls.
 */
MyClass.prototype.myMethod = function (arg1, arg2) {
     // - don't use this.parentClass -- won't work if hierarchy is more than one deep
     // - use apply(this, arguments) instead of call(this, arg1, arg2) so we don't have to fix it up
     //   every time we add a new argument
     MyClass.prototype.parentClass.myMethod.apply(this, arguments);
     // ... 
};

On Arrays, use Array.prototype.forEach or _.each rather than for loops:

Do this:

var anArray = [1, 2, 3, 4];
anArray.forEach(function (value, index) {  // OK!
    // ...
});

Or this:

var _ = require("lodash");
_.each(anArray, function (value, index) {  // OK
    // ...
})

Not this:

for (var i = 0; i < anArray.length; i++) {  // Use Array.prototype.forEach()
    // ...
}

When in doubt, use lodash!

• All comments should be C++ single line style //comment.
• Even multiline comments should use // at the start of each line
• Use C style /* comments */ for notices at the top and bottom of the file
• Use JSDoc tags for annotations with Google's Closure Compiler Type Expressions, see https://developers.google.com/closure/compiler/docs/js-for-compiler
• Annotations should use the /** annotation */
• Annotate all non-anonymous functions

• Use exceptions when encountering an unexpected error and recovery is not possible. In other words, the error means that Playground will be noticeably broken or data could be corrupted if execution continues.
• Use console.error() or console.assert() when encountering an unexpected error that can be recovered from. In other words, an error occurred and the current operation may not complete successfully, but the overal integrity of the program is not compromised.
• Use console.log() to note unexpected behavior that is not necessarily an error.

NOTE console.log() should not be used to log general information.

The Document constructor throws an error if a document already exists for the current file. Creating a new document that points to the same file could lead to file corruption if both documents are edited.

function Document(file, initialTimestamp, rawText) {
    ...
    if (_openDocuments[file.fullPath]) {
        throw new Error("Creating a document when one already exists, for: " + file);
    }
    ...
}

In DocumentManager.closeFullEditor(), after opening the next file, we check that the currentDocument property is updated correctly. This is an error if not true, and may lead to unexpected behavior, but it is not catastrophic.

CommandManager.execute(Commands.FILE_OPEN, { fullPath: nextFile.fullPath })
    .done(function () {
        // (Now we're guaranteed that the current document is not the one we're closing)
        console.assert(!(_currentDocument && _currentDocument.file.fullPath === file.fullPath));
    })

The CommandManager.register() function uses console.log() to note an unexpected (but not dangerous) condition -- the specified command id has already been registered. The code can continue safely from here.

function register(name, id, commandFn) {
    if (_commands[id]) {
        console.log("Attempting to register an already-registered command: " + id);
        return null;
    }
    ...
}

We prefer both using and presenting asynchronous instead of synchronous APIs. We present asynchronous APIs by exposing functions that return promises instead of callbacks. Clients can rely on the promises that we return from our API calls to satisfy the Promises A/+ specification as well as the ES6 Promise specification. Internally we use the Bluebird promise library, but external clients should not rely on features specific to that implementation.

Two notes for contributors who are primarily used to working with jQuery promises:

1. jQuery promises are not guaranteed to be asynchronous, whereas Bluebird (and other A/+ conforming promise implementations) are. This means that getPromise().then(fn) will never execute fn in the same tick of the event loop as getPromise.
2. The use of deferred objects is to be avoided when possible. When possible, use the new Promise(function(resolve, reject) { /* ... */ }) pattern instead.