User:GavinSharp/JS Style Guidelines

  • Revision slug: User:GavinSharp//JS_Style_Guidelines
  • Revision title: User:GavinSharp/JS Style Guidelines
  • Revision id: 199842
  • Created:
  • Creator: GavinSharp
  • Is current revision? No
  • Comment /* JavaScript features */

Revision Content

Spaces, wrapping, and indentation

  • No tabs!
  • Lines should not contain trailing spaces, even after binary operators, commas or semicolons.
  • Operators should be seperated by a space
  • Spaces after commas and semicolons, but not before.
  • Spaces after keywords, e.g. if (x > 0).
  • Two space indentation is standard.
  • Lines should wrap at 80 characters where possible.
  • One (or two) blank lines between block definitions. Also consider breaking up large code blocks with blank lines.
  • End the file with a newline.
  • Keep operators at the end of the line when wrapping conditions.
  • Try to indent to line up with a related item on the previous line.

Examples:

if (reallyReallyLongCondition() && someOtherLongThing() &&
    somethingShorter()) {
  ...
}

var result = prompt(message, initialValue,
                    caption);

Brackets

  • No brackets around single line code blocks.
  • Single statements surrounded by comments should be bracketted. Minimize newlines before brackets (bracket should always be on the same line as "if" or "else").

Examples:

if (foo.bar())
  doBar();
else
  runAway();

if (foo.bar()) {
  // Comment here
  doBar();
} else
  runAway();

if (foo.bar()) {
  // Multi-line
  // Comment here
  doBar();
} else {
  // Another comment
  runAway();
}

Function and variable names

  • Function and variable names should be interCaps, first letter lowercase.
  • All functions should have names (i.e. no anonymous functions).
  • Contstants should be in UPPER_CASE.
  • Arguments (parameter names) should be prefixed with the letter a, and be as descriptive as possible.
  • Event handler functions should be prefixed with the word on, in particular try to use the names onLoad, onDialogAccept, onDialogCancel etc. where this is unambiguous.
  • Try to declare local variables as near to their use as possible; try to initialize every variable.

Examples:

function myFooFunction(aArg1, aArg2) {
  ...
}
var obj = {
  myFooFunction: function obj_myFooFunc(aArg1, aArg2) {
    var local = aArg1 + " foo";
    this.anotherFunction(local);
  },

  anotherFunction: function obj_anotherFunction(aArg1) {
    ...
  }
}

JavaScript features

  • Make sure that your code doesn't generate any strict JavaScript warnings, such as:
    • Duplicate variable declaration
    • Mixing return; with return value;
    • Trailing comma in JavaScript object declarations
    • Undeclared variables or members. If you are unsure if an array value exists, compare the index to the array's length. If you are unsure if an object member exists, use "name" in aObject.
  • Prefer literal object notation (var obj = {}; over var obj = new Object();).
  • Similarly, with arrays, prefer var a = {{mediawiki.external('1, a, 3')}} to var a = new Array(1, a, 3);.
  • Private members should be prefixed with "_". Example:
var myObj = {
  _private: 42,
  _privFunction: function myObj__privF(aArg) {
    return aArg + 2;
  },
  pubFunction: function myObj_myPF(aArg) {
    return this._privFunction(aArg) * this._private;
  }
}

XPCOM

  • Favor the use of Cc/Ci/Cr constants for Components.classes/Components.interfaces/Components.results
  • Periods kept at the end of the line when wrapping, indent wrapped lines to match up with space after equal sign.

Examples:

const Ci = Components.interfaces;
const Cc = Components.classes;
const Cr = Components.results;

var fooBar = Cc["@mozilla.org/foo-bar;1"].getService(Ci.nsIFooBar);

var longerFooBar = Cc["@mozilla.org/longer-foo-bar;1"].
                   getService(Ci.nsILongerFooBar);

Revision Source

<h3 name="Spaces.2C_wrapping.2C_and_indentation">Spaces, wrapping, and indentation</h3>
<ul><li>No tabs!
</li><li>Lines should not contain trailing spaces, even after binary operators, commas or semicolons.
</li><li>Operators should be seperated by a space
</li><li>Spaces after commas and semicolons, but not before.
</li><li>Spaces after keywords, e.g. <code>if (x &gt; 0)</code>.
</li><li>Two space indentation is standard.
</li><li>Lines should wrap at 80 characters where possible.
</li><li>One (or two) blank lines between block definitions. Also consider breaking up large code blocks with blank lines.
</li><li>End the file with a newline.
</li><li>Keep operators at the end of the line when wrapping conditions.
</li><li>Try to indent to line up with a related item on the previous line.
</li></ul>
<p>Examples:
</p>
<pre>if (reallyReallyLongCondition() &amp;&amp; someOtherLongThing() &amp;&amp;
    somethingShorter()) {
  ...
}

var result = prompt(message, initialValue,
                    caption);
</pre>
<h3 name="Brackets">Brackets</h3>
<ul><li>No brackets around single line code blocks.
</li><li>Single statements surrounded by comments should be bracketted. Minimize newlines before brackets (bracket should always be on the same line as "if" or "else").
</li></ul>
<p>Examples:
</p>
<pre>if (foo.bar())
  doBar();
else
  runAway();

if (foo.bar()) {
  // Comment here
  doBar();
} else
  runAway();

if (foo.bar()) {
  // Multi-line
  // Comment here
  doBar();
} else {
  // Another comment
  runAway();
}
</pre>
<h3 name="Function_and_variable_names">Function and variable names</h3>
<ul><li>Function and variable names should be interCaps, first letter lowercase.
</li><li>All functions should have names (i.e. no anonymous functions).
</li><li>Contstants should be in UPPER_CASE.
</li><li>Arguments (parameter names) should be prefixed with the letter a, and be as descriptive as possible.
</li><li>Event handler functions should be prefixed with the word on, in particular try to use the names onLoad, onDialogAccept, onDialogCancel etc. where this is unambiguous.
</li><li>Try to declare local variables as near to their use as possible; try to initialize every variable.
</li></ul>
<p>Examples:
</p>
<pre>function myFooFunction(aArg1, aArg2) {
  ...
}
var obj = {
  myFooFunction: function obj_myFooFunc(aArg1, aArg2) {
    var local = aArg1 + " foo";
    this.anotherFunction(local);
  },

  anotherFunction: function obj_anotherFunction(aArg1) {
    ...
  }
}
</pre>
<h3 name="JavaScript_features">JavaScript features</h3>
<ul><li>Make sure that your code doesn't generate any strict JavaScript warnings, such as:
<ul><li>Duplicate variable declaration
</li><li>Mixing <code>return;</code> with <code>return value;</code>
</li><li>Trailing comma in JavaScript object declarations
</li><li>Undeclared variables or members.  If you are unsure if an array value exists, compare the index to the array's length. If you are unsure if an object member exists, use "name" in aObject.
</li></ul>
</li><li>Prefer literal object notation (<code>var obj = {};</code> over <code>var obj = new Object();</code>).
</li><li>Similarly, with arrays, prefer <code>var a = {{mediawiki.external('1, a, 3')}}</code> to <code>var a = new Array(1, a, 3);</code>.
</li><li>Private members should be prefixed with "_". Example:
</li></ul>
<pre>var myObj = {
  _private: 42,
  _privFunction: function myObj__privF(aArg) {
    return aArg + 2;
  },
  pubFunction: function myObj_myPF(aArg) {
    return this._privFunction(aArg) * this._private;
  }
}
</pre>
<h3 name="XPCOM">XPCOM</h3>
<ul><li>Favor the use of Cc/Ci/Cr constants for Components.classes/Components.interfaces/Components.results
</li><li>Periods kept at the end of the line when wrapping, indent wrapped lines to match up with space after equal sign.
</li></ul>
<p>Examples:
</p>
<pre>const Ci = Components.interfaces;
const Cc = Components.classes;
const Cr = Components.results;

var fooBar = Cc["@mozilla.org/foo-bar;1"].getService(Ci.nsIFooBar);

var longerFooBar = Cc["@mozilla.org/longer-foo-bar;1"].
                   getService(Ci.nsILongerFooBar);
</pre>
Revert to this revision