Always use UNIX style line termination with a single new line character `\n`.
File names
----------
To avoid problems with non case sensitive file systems (Windows) only alphanumeric characters, underscores, and the dash character ("-") are permitted. Spaces are strictly prohibited.
*Right:*
elements/bar.js
core/parsers/aml.js
elements/teleport/rpc/jsonrpc.js
*Wrong:*
elements/Bar.js
rpc/Json Rpc.js
Semicolons
----------
There are [rebellious forces][isaac] that try to steal your semicolons from you. But make no mistake, our traditional culture is still [well and truly alive][hnsemicolons]. So follow the community, and use those semicolons!
Just like you brush your teeth after every meal, you clean up any trailing whitespace in your JavaScript files before committing. Otherwise the rotten smell of careless neglect will eventually drive away contributors and/or co-workers.
Line length
-----------
The target line length is 80 characters. That is to say, developers should strive keep each line of their code under 80 characters where possible and practical. However, longer lines are acceptable in some circumstances. The maximum length of any line of code is 120 characters.
Quotes
------
When a string is literal (contains no variable substitutions), the quotation mark or "double quote" should always be used to demarcate the string:
```javascript
var a = "Example String";
```
When a literal string itself contains quotation marks, it is permitted to demarcate the string with apostrophes or "single quotes". This is especially useful for blocks of HTML:
```javascript
var a = '<divclass="button">' +
'<ahref="#"title="Click me">Click me</a>' +
'</div>';
```
## Braces
Your opening braces go on the same line as the statement.
*Right:*
```javascript
if (true) {
console.log("winning");
}
```
*Wrong:*
```javascript
if (true)
{
console.log("losing");
}
```
Also, notice the use of whitespace before and after the condition statement.
If the block inside the curlys consists only of one statement the curlys may be omitted.
```javascript
if (err)
return callback(err);
```
However within one condition curlys must be used consistently.
*Right:*
```javascript
if (true) {
var msg = "winning" + name;
console.log(msg);
}
else {
console.log("Oh noo");
}
```
*Wrong:*
```javascript
if (true) {
var msg = "winning" + name;
console.log(msg);
}
else
console.log("Oh noo");
```
Always use a new line after after `if`, `while`, `for`, `do` and `try`.
*Right:*
```javascript
if (err)
return callback(err);
```
*Wrong:*
```javascript
if (err) return callbak(err);
```
Variable declarations
---------------------
Declare one variable per var statement, it makes it easier to re-order the lines. Ignore [Crockford][crockfordconvention] on this, and put those declarations wherever they make sense.
Variables and properties should use [lower camel case][camelcase] capitalization. They should also be descriptive. Single character variables, uncommon abbreviations and hungarian notation should generally be avoided.
*Right:*
```javascript
var adminUser = db.query("SELECT * FROM users ...");
var isAdmin = adminUser !== "";
```
*Wrong:*
```javascript
var admin_user = d.query("SELECT * FROM users ...");
Class names should be capitalized using [upper camel case][camelcase].
*Right:*
```javascript
function BankAccount() {
}
```
*Wrong:*
```javascript
function bank_Account() {
}
```
Constants
---------
Constants should be declared as regular variables or static class properties, using all uppercase letters.
Node.js / V8 actually supports mozilla's [const][const] extension, but unfortunately that cannot be applied to class members, nor is it part of any ECMA standard.
Do not extend the prototypes of any objects, especially native ones. There is a special place in hell waiting for you if you don't obey this rule.
*Right:*
```javascript
var a = [];
if (!a.length) {
console.log("winning");
}
```
*Wrong:*
```javascript
Array.prototype.empty = function() {
return !this.length;
}
var a = [];
if (a.empty()) {
console.log("losing");
}
```
Function length
---------------
Keep your functions short. A function that doesn't fit on a 13" Notebook screen is too long. Limit yourself to max. 30 lines. Less is better.
Return statements
-----------------
To avoid deep nesting of if-statements, always return a functions value as early
as possible.
*Right:*
```javascript
function isPercentage(val) {
if (val <0)
return false;
if (val > 100)
return false;
return true;
}
```
*Wrong:*
```javascript
function isPercentage(val) {
if (val >= 0) {
if (val <100){
return true;
}
else {
return false;
}
}
else {
return false;
}
}
```
Or for this particular example it may also be fine to shorten things even further:
```javascript
function isPercentage(val) {
var isInRange = (val >= 0 && val <= 100);
return isInRange;
}
```
Named closures
--------------
Feel free to give your closures a name. It shows that you care about them, and will produce better stack traces:
```javascript
req.on("end", function onEnd() {
console.log("winning");
});
```
Callbacks
---------
Since node is all about non-blocking I/O, functions generally return their results using callbacks. The convention used by the node core is to reserve the first parameter of any callback for an optional error object.
You should use the same approach for your own callbacks.
If a function takes a callback some limitations apply:
1. the callback must be the last argument and the argument name should be 'callback'
2. the callback must be called exactly once
3. the function must now throw an exception. Exceptions must be caught and passed to the callback as first argument
Node.js ships with a simple EventEmitter class that can be included from the 'events' module:
```javascript
var EventEmitter = require("events").EventEmitter;
```
When creating complex classes, it is common to inherit from this EventEmitter class to emit events. This is basically a simple implementation of the [Observer pattern][].
However, I strongly recommend that you never listen to the events of your own class from within it. It isn't natural for an object to observe itself. It often leads to undesirable exposure to implementation details, and makes your code more difficult to follow.
Class Definition
----------------
```javascript
var Ide = module.exports = function() {};
(function() {
this.member = function() {};
}).call(Ide.prototype);
```
Within a JavaScript file only one class definition is permitted.
Inheritance
-----------
```javascript
var RunvmPlugin = module.exports = function(ide, workspace) {
Plugin.call(this, ide, workspace);
// ...
}
sys.inherits(RunvmPlugin, Plugin);
(function() {
this.member = function() {};
}).call(RunvmPlugin.prototype);
```
Private function
----------------
Private functions attached to the constructor (static) of the prototype of a class must be prefixed with an underscore.
```javascript
var Ide = module.exports = function() {};
Ide._privateField = "private data";
(function() {
this._privateMethod = function() {};
}).call(Ide.prototype);
```
How to break long lines
-----------------------
Treat parenthesis and square brackets like curly braces:
* they start in the same line as the function
* the body (argument list) is indented one level
* the closing parenthesis is outdented and on a separate line
*Right:*
```javascript
foo(
very, long argument,
list, with lots, of,
different, stuff
);
```
*Wrong:*
```javascript
foo(very, long argument, list, with lots, of,
different, stuff);
```
The same applies for long array literals.
*Right:*
```javascript
var a = [
'<divclass="button">',
' <ahref="#"title="Click me">Click me</a>',
'</div>'
].join("");
```
*Wrong:*
```javascript
var a = ['<divclass="button">',
' <ahref="#"title="Click me">Click me</a>',
'</div>'].join("");
```
When breaking up long expressions the operator should be on the new line and broken lines should be indented by one level.
*Right:*
```javascript
var isAdmin = isLoggedIn
&& username === "admin"
&& password === "secret";
```
*Wrong:*
```javascript
var isAdmin = isLoggedIn &&
username === "admin" &&
password === "secret";
```
The same is true for the ternary operator:
```javascript
var a = (value > 20 && otherValue <10&&boolFoo ===false)
? this.foo();
: this.bar();
```
For Loops
---------
If statements are incredibly flexible. The condition, test and increment part of an if statement can contain any code. However to make it easy for others to understand the code you should stay away from the crazy shit and limit yourself to the straighforard cases:
1. declare the loop and length variables inline.
2. Don't declare any other variables in the initializer
*Right:*
```javascript
for (var i = 0, l = users.length; i <l;i++){
var user = users[i];
//
}
```
*Wrong:*
```javascript
var i, l;
for (i = 0, l = users.length; i <l;i++){
var user = users[i];
//
}
for (var user, i = 0, l = users.length; i++ <l;){
var user = users[i];
//
}
```
Switch Statements
-----------------
Control statements written with the "switch" statement must have a single space before the opening parenthesis of the conditional statement and after the closing parenthesis.
All content within the "switch" statement must be indented using four spaces. Content under each "case" statement must be indented using an additional four spaces.
```javascript
switch (numPeople) {
case 1:
break;
case 2:
break;
default:
break;
}
```
The construct default should never be omitted from a switch statement.
NOTE: It is sometimes useful to write a case statement which falls through to the next case by not including a break or return within that case. To distinguish these cases from bugs, any case statement where break or return are omitted should contain a comment indicating that the break was intentionally omitted.
Vertical alignment
------------------
Vertically aligning asignments can improve readability but also makes it harder to maintain the code. The style should be avoided.
*Right*:
```javascript
var foo = 12;
var firstName = "Peter";
var options = {
name: firstName,
age: {
years: 12,
months: 1
}
};
```
*Wrong*:
```javascript
var foo = 12;
var firstName = "Peter";
var options = {
name : firstName,
age : {
years : 12,
months : 2
}
};
```
_self = this
-----------
The alias to access `this` from within closures is `_self` or `that`. We do not use `self` to avoid confusion with `window.self` in client side code.
API Documentation
-----------------
All classes and public API should be documented using [JSDuck annotations](https://github.com/senchalabs/jsduck).
