Montage Framework Style Guide (draft)

This style guide includes recommended practices for consistency. If any of the rules conflicts with readability in a particular case, ignore the rules and chose readability.

Code Format
Commit Message Format
Naming Conventions
Javascript
Docs

General Code Format

Set your editor to use below settings. Optionally use http://EditorConfig.org.

Character set UTF-8
Indent: 4 spaces (there should be no tabs in the codebase)
Line ending: LF (Unix-style)
Trim trailing whitespace
Max line length: keep it reasonable

Not settable by EditorConfig:

Function declaration
- Anonymous: function () {}, not function() {}
- Named: function foo() {}, not function foo () {}
Function invocation func(arg), not func (arg)
No leading or trailing spaces, for example, (arg) not ( arg )
Space after , & ; unless end of line. For example:
- [1, 2, 3, 4, 5, 6]
- for (i = 0; i < length; i++)
1 + 1, not 1+1
Space before & after comment blocks
- // comment not //comment
- /* comment */ not /*comment*/
Serialization bracing in HTML template, as generated by minit:

<script type="text/montage-serialization">
{
    "owner": {
        "properties": {
            "element": {"#": "main"}
        }
    }
}
</script>

Commit Message Format

50/72 style, more @ http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html, for example,:

50 1st line, 1st word capitalized, no period

(blank line)

72 3rd & following lines

Use imperative verbs - "add", not "adds" / "added" / "adding"

Naming Conventions

General

Do not abbreviate unless if it's a well known term, for example, abbreviate min, max, config, don't abbreviate EarthquakeOverlay into EQOverlay

JavaScript

Components & prototypes - must be upper CamelCase, for example, ComponentFoo; prototype name in serialization block auto converted to such case
Boolean flags - prefix with is or has, for example, isFoo
Private variable name - prefix with _, for example, _foo
Constant variable name - EMPTY_ARRAY
Prefer self over that or me, etc., for example, var self = this;

CSS

For components in Montage Framework & associated UI sets, always prefix with a namespace. For example, .montage-ComponentFoo, .digit-ComponentFoo.
For apps using Montage Framework, we also recommend to optionally prefix with app name to distinguish source of components. For example, .myApp-ComponentFoo.

Files & Directories

component-foo.reel

TODO: to be merged in: https://github.com/montagejs/montage/wiki/Naming-Conventions

Order

Prefer alphabetical ordering, unless the natural order of a sequence would be immediately obvious to anyone reading the code. For requires, switch cases, etc.

JavaScript

Terminate statements with ;
Declare variables at top of block
Declare multiple variables with single var statement & commas; can do in 1 line if not many variables
Define constructor function at top of block
Use K&R style braces, { at end of line, for example,:

return {
   status: 'ok'
};

No braces for 1-line if statements
Prefer === and !== unless need == or != behaviour
strict mode - TBD
Multiline string

var longString = 'A rather long string of English text, an error message ' +
        'actually that just keeps going and going';

Getters before setters
Indent method chains, for example:

loadFile
    .then()
    .then()
    .catch()

Error handling

TBD

Performance

Async - prefer callback over promises in implementation, where performance matters; prefer promises in MontageJS APIs
Prefer for or do-while loops over forEach
Avoid closures

Hinting - TBD
Testing - Jasmine + montage-testing

Docs

Write in JSDoc + markdown
Prefer standard tags over synonyms, for example, @function, not @func or @method
Prefer .prototype over # due to lack of JSDoc documentation on # and lack of support for it in certain editors, such as WebStorm

Comment style

/**
 * @private
 * @property {Object[]} value
 */

// not

/**
 @private
 @property {Object[]} value
 */

Getter / setters

If setting a private variable, document everything on getter / setter; if not, document on private variable.

/**
 * Description
 *
 * @property {PressComposer} value
 * @default null
 * @private
 */
_pressComposer: {
    value: null
},

/**
 * @private
 */
_active: {
    value: false
},

/**
 * Description
 *
 * @property {boolean}
 * @default false
 */
active: {
    get: function () {
        return this._active;
    },
    set: function (value) {
        this._active = value;
        this.needsDraw = true;
    }
},

rayshan/STYLE.md