Grasshopper JavaScript Style Guide() {

A mostly reasonable approach to JavaScript adapted from Airbnb

TL;DR

Readability and understandability are the goals
Whitespace is king
Variables & functions are camelCased
Always use 4 space indents
4 line returns between functions
Line return above comment
Line returns at top and bottom of functions and objects

Types

Primitives: When you access a primitive type you work directly on its value
- string
- number
- boolean
- null
- undefined
```
var foo = 1,
    bar = foo;

bar = 9;

console.log(foo, bar); // => 1, 9
```

Complex: When you access a complex type you work on a reference to its value

object
array
function

var foo = [1, 2],
    bar = foo;

bar[0] = 9;

console.log(foo[0], bar[0]); // => 9, 9

[↑]

Objects

Use the literal syntax for object creation.

// bad
var item = new Object();

// good
var item = {};

Don't use reserved words as keys.

// bad
var superman = {

  class: 'superhero',
  default: { clark: 'kent' },
  private: true

};

// good
var superman = {

  klass: 'superhero',
  defaults: { clark: 'kent' },
  hidden: true

};

[↑]

Arrays

Use the literal syntax for array creation

// bad
var items = new Array();

// good
var items = [];

If you don't know array length use Array#push.

var someStack = [];


// bad
someStack[someStack.length] = 'abracadabra';

// good
someStack.push('abracadabra');

When you need to copy an array use Array#slice. jsPerf

var len = items.length,
    itemsCopy = [],
    i;

// bad
for (i = 0; i < len; i++) {

  itemsCopy[i] = items[i];

}

// good
itemsCopy = Array.prototype.slice.call(items);

[↑]

Strings

Use single quotes '' for strings

// bad
var name = "Bob Parr";

// good
var name = 'Bob Parr';

// bad
var fullName = "Bob " + this.lastName;

// good
var fullName = 'Bob ' + this.lastName;

Much research has gone into this issue and we arrive at using string concatenation over string literals because of the compile-time inconsistencies seen across browsers using string literals.

See Google's Style Guide for support

// bad
var errorMessage = 'This is a super long error that was thrown because of Batman. When you stop to think about how Batman had anything to do with this, you would get nowhere fast.';

// bad
var errorMessage = 'This is a super long error that \
was thrown because of Batman. \
When you stop to think about \
how Batman had anything to do \
with this, you would get nowhere \
fast.';


// good
var errorMessage = 'This is a super long error that ' +
  'was thrown because of Batman.' +
  'When you stop to think about ' +
  'how Batman had anything to do ' +
  'with this, you would get nowhere ' +
  'fast.';

When programatically building up a string, use Array#join instead of string concatenation. Mostly for IE: jsPerf.

var items,
    messages,
    length, i;

messages = [{

    state: 'success',
    message: 'This one worked.'

},

{

    state: 'success',
    message: 'This one worked as well.'

},

{

    state: 'error',
    message: 'This one did not work.'

}];

length = messages.length;

// bad
function inbox (messages) {

  items = '<ul>';

  for (i = 0; i < length; i++) {

    items += '<li>' + messages[i].message + '</li>';

  }

  return items + '</ul>';

}

// good
function inbox (messages) {

  items = [];

  for (i = 0; i < length; i++) {

    items[i] = messages[i].message;

  }

  return '<ul><li>' + items.join('</li><li>') + '</li></ul>';

}

[↑]

Embedded HTML

Always use single quotes for javascript and double quotes for HTML attributes

// Bad (no mixing in JS expressions)
$(".selector").on('click', function(){

    // do stuff

});

// Bad (using single quotes in HTML attributes is sloppy and not best practice)
$("ul").append("<li class='myclass'>information</li>");

// Right, but not very readable
$("ul").append("<li class=\"myclass\">information</li>");

// Good - best option
$('ul').append('<li class="myclass">information</li>');

Functions

Function expressions:

// anonymous function expression
var anonymous = function() {

  return true;

};

// named function expression
var named = function named () {

  return true;

};

// immediately-invoked function expression (IIFE)
(function() {

  console.log('Welcome to the Internet. Please follow me.');

})();

Never declare a function in a non-function block (if, while, etc). Assign the function to a variable instead. Browsers will allow you to do it, but they all interpret it differently, which is bad news bears.

Note: ECMA-262 defines a block as a list of statements. A function declaration is not a statement. Read ECMA-262's note on this issue.

// bad
if (currentUser) {

  function test () {

    console.log('Nope.');

  }
}

// good
if (currentUser) {

  var test = function test () {

    console.log('Yup.');

  };

}

// better
var test = function test () {
    
    console.log("Yup.");
    
}

if (currentUser) {
    
    test();
    
}

Never name a parameter arguments, this will take precedence over the arguments object that is given to every function scope.

// bad
function nope (name, options, arguments) {

  // ...stuff...

}

// good
function yup (name, options, args) {

  // ...stuff...

}

[↑]

Properties

Use dot notation when accessing properties.

var luke = {

  jedi: true,
  age: 28

};

// bad
var isJedi = luke['jedi'];

// good
var isJedi = luke.jedi;

Use subscript notation [] when accessing properties with a variable.

var luke = {

  jedi: true,
  age: 28

};

function getProp(prop) {

  return luke[prop];

}

var isJedi = getProp('jedi');

[↑]

Variables

Always use var to declare variables. Not doing so will result in global variables. We want to avoid polluting the global namespace. Captain Planet warned us of that.
```
// bad
superPower = new SuperPower();

// good
var superPower = new SuperPower();
```

Use one var declaration for multiple variables and declare each variable on a newline.

// bad
var items = getItems();
var goSportsTeam = true;
var dragonball = 'z';

// good
var items = getItems(),
    goSportsTeam = true,
    dragonball = 'z';

Declare unassigned variables last. This is helpful when later on you might need to assign a variable depending on one of the previous assigned variables.

// bad
var i, len, dragonball,
    items = getItems(),
    goSportsTeam = true;

// bad
var i, items = getItems(),
    dragonball,
    goSportsTeam = true,
    len;

// good
var items = getItems(),
    goSportsTeam = true,
    dragonball,
    length,
    i;

Assign variables at the top of their scope. This helps avoid issues with variable declaration and assignment hoisting related issues.

// bad
function() {

  test();
  console.log('doing stuff..');

  //..other stuff..

  var name = getName();

  if (name === 'test') {

    return false;

  }

  return name;

}

// good
function() {

  var name = getName();

  test();

  console.log('doing stuff..');

  //..other stuff..

  if (name === 'test') {

    return false;

  }

  return name;

}

// bad
function() {

  var name = getName();

  if (!arguments.length) {

    return false;

  }

  return true;

}

// good
function() {
    
  if (!arguments.length) {

    return false;

  }

  var name = getName();

  return true;

}

[↑]

Hoisting

Variable declarations get hoisted to the top of their scope, their assignment does not.

// we know this wouldn't work (assuming there
// is no notDefined global variable)
function example () {

  console.log(notDefined); // => throws a ReferenceError

}

// creating a variable declaration after you
// reference the variable will work due to
// variable hoisting. Note: the assignment
// value of `true` is not hoisted.
function example () {

  console.log(declaredButNotAssigned); // => undefined
  var declaredButNotAssigned = true;

}

// The interpreter is hoisting the variable
// declaration to the top of the scope.
// Which means our example could be rewritten as:
function example () {

  var declaredButNotAssigned;
  console.log(declaredButNotAssigned); // => undefined
  declaredButNotAssigned = true;

}

Anonymous function expressions hoist their variable name, but not the function assignment.

function example () {

  console.log(anonymous); // => undefined

  anonymous(); // => TypeError anonymous is not a function

  var anonymous = function() {

    console.log('anonymous function expression');

  };

}

Named function expressions hoist the variable name, not the function name or the function body.

function example () {

  console.log(named); // => undefined

  named(); // => TypeError named is not a function

  superPower(); // => ReferenceError superPower is not defined

  var named = function superPower() {

    console.log('Flying');

  };


  // the same is true when the function name
  // is the same as the variable name.
  function example () {

    console.log(named); // => undefined

    named(); // => TypeError named is not a function

    var named = function named() {

      console.log('named');

    };

  }

}

Function declarations hoist their name and the function body.

function example () {

  superPower(); // => Flying

  function superPower () {

    console.log('Flying');

  }

}

For more information refer to JavaScript Scoping & Hoisting by Ben Cherry

[↑]

Conditional Expressions & Equality

Use === and !== over == and !=.
Conditional expressions are evaluated using coercion with the ToBoolean method and always follow these simple rules:
- Objects evaluate to true
- Undefined evaluates to false
- Null evaluates to false
- Booleans evaluate to the value of the boolean
- Numbers evalute to false if +0, -0, or NaN, otherwise true
- Strings evaluate to false if an empty string '', otherwise true
```
if ([0]) {
  // true
  // An array is an object, objects evaluate to true
}
```

Use shortcuts.

// bad
if (name !== '') {
  // ...stuff...
}

// good
if (name) {
  // ...stuff...
}

// bad
if (collection.length > 0) {
  // ...stuff...
}

// good
if (collection.length) {
  // ...stuff...
}

For more information see Truth Equality and JavaScript by Angus Croll

// Formatting long conditionals
if (firstCondition === true
    && secondCondition === true
    && thirdCondition === false) {

    // do stuff

}

// more complicated
if ((firstCondition === true
    && secondCondition === false)
    ||
    (thirdCondition === false
    && fourthCondition === true)) {

    // do stuff

}

[↑]

Blocks

Use braces with all multi-line blocks.

Do not use single line blocks

// bad
if (test)
  return false;

// bad (no single line code with no curlies)
if (test) return false;

// good
if (test) {
    
  return false;
  
}

// good
function() {
    
  return false;
  
}

[↑]

Comments

Use /** ... */ for multiline comments.
Use words that people can understand.
Don't state the obvious

Comments go above (not next to) the block they describe

// bad
// make() returns a new element
// based on the passed in tag name
//
// @param <String> tag
// @return <Element> element
function make (tag) {

  // ...stuff...

  return element;

}

// bad (no comments to the side; don't state the obvious)
function () {
    
    if (stuff) { //this tests for "stuff"
        
        return true;
        
    }
    
}

// good
/**
 * make() returns a new element
 * based on the passed in tag name
 */
function make (tag) {

  // ...stuff...
  return element;

}

Use // for single line comments. Place single line comments on a newline above the subject of the comment. Put an emptyline before the comment.

There should always be a line return before each comment to create visual separation from the previous line.

// bad
var active = true;  // is current tab

// good
// is current tab
var active = true;

// bad
function getType() {
  console.log('fetching type...');
  // set the default type to 'no type'
  var type = this._type || 'no type';

  return type;

}

// good
function getType() {
  console.log('fetching type...');

  // set the default type to 'no type'
  var type = this._type || 'no type';

  return type;

}

[↑]

Whitespace

Use soft tabs set to 4 spaces

// bad
function() {

∙var name;

}

// bad
function() {

∙∙var name;

}

// good
function() {

∙∙∙∙var name;

}

Place 1 space before the argument parentheses and before the leading brace.

// bad
function test(){

  console.log('test');

}

// bad
function test() {

  console.log('test');

}

// good
function test () {

  console.log('test');

}

// bad
dog.set('attr',{

  age: '1 year',
  breed: 'Bernese Mountain Dog'

});

// good
dog.set('attr', {

  age: '1 year',
  breed: 'Bernese Mountain Dog'

});

[↑]

Leading Commas

Nope.

// bad
var once
  , upon
  , aTime;

// good
var once,
    upon,
    aTime;

// bad
var hero = {

    firstName: 'Bob'
  , lastName: 'Parr'
  , heroName: 'Mr. Incredible'
  , superPower: 'strength'

};

// good
var hero = {

  firstName: 'Bob',
  lastName: 'Parr',
  heroName: 'Mr. Incredible',
  superPower: 'strength'

};

[↑]

Semicolons

Yup.

// bad
(function() {

  var name = 'Skywalker'
  return name

})()

// good
(function() {

  var name = 'Skywalker';
  return name;

})();

// good
/**
* Adding a semicolon to the beginning of a function
* escapes poorly written JS before the function it precedes.
* This technique is most useful in 3rd party JS and shouldn't
* be considered standard practice.
*/
;(function() {

  var name = 'Skywalker';
  return name;

})();

[↑]

Type Casting & Coercion

Perform type coercion at the beginning of the statement.

Strings:

//  => this.reviewScore = 9;

// bad
var totalScore = this.reviewScore + '';

// bad
var totalScore = '' + this.reviewScore;

// good
var totalScore = this.reviewScore.toString();

// bad
var totalScore = '' + this.reviewScore + ' total score';

// good
var totalScore = this.reviewScore + ' total score';

Use parseInt for Numbers and always with a radix for type casting.

If for whatever reason you are doing something wild and parseInt is your bottleneck and need to use Bitshift for performance reasons, leave a comment explaining why and what you're doing.

var inputValue = '4';

// bad
var val = new Number(inputValue);

// bad
var val = +inputValue;

// bad
var val = inputValue >> 0;

// bad
var val = parseInt(inputValue);

// good
var val = Number(inputValue);

// good
var val = parseInt(inputValue, 10);

// good
/**
 * parseInt was the reason my code was slow.
 * Bitshifting the String to coerce it to a
 * Number made it a lot faster.
 */
var val = inputValue >> 0;

[↑]

Naming Conventions

Avoid single letter names. Be descriptive with your naming.

// bad
function q () {
  // ...stuff...
}

// good
function query () {
  // ..stuff..
}

Use camelCase when naming objects, functions, and instances

// bad
var OBJEcttsssss = {};
var this_is_my_object = {};
var this-is-my-object = {};
function c () {};
var u = new user({

  name: 'Bob Parr'

});

// good
var thisIsMyObject = {};
function thisIsMyFunction () {};
var user = new User({

  name: 'Bob Parr'

});

First, have a really good reason to use Constructors and Classes

Use PascalCase when naming constructors or classes

// bad
function user(options) {
  this.name = options.name;
}

var bad = new user({
  name: 'nope'
});

// good
function User(options) {
  this.name = options.name;
}

var good = new User({
  name: 'yup'
});

Use a leading underscore _ when naming private properties

// bad
this.__firstName__ = 'Panda';
this.firstName_ = 'Panda';

// good
this._firstName = 'Panda';

When saving a reference to this use _this.

// bad
function() {

  var self = this;

  return function() {

    console.log(self);

  };

}

// bad
function() {

  var that = this;

  return function() {

    console.log(that);

  };

}

// good
function() {

  var _this = this;

  return function() {

    console.log(_this);

  };

}

Name your functions. This is helpful for stack traces.

// bad
var log = function (msg) {

  console.log(msg);

};

// good
var log = function log (msg) {

  console.log(msg);

};

[↑]

Accessors

Accessor functions for properties are not required

If you do make accessor functions use getVal() and setVal('hello')

// bad
dragon.age();

// good
dragon.getAge();

// bad
dragon.age(25);

// good
dragon.setAge(25);

If the property is a boolean, use isVal() or hasVal()

// bad
if (!dragon.age()) {

  return false;

}

// good
if (!dragon.hasAge()) {

  return false;

}

It's okay to create get() and set() functions, but be consistent.

function Jedi(options) {

  options || (options = {});
  var lightsaber = options.lightsaber || 'blue';
  this.set('lightsaber', lightsaber);

}

Jedi.prototype.set = function(key, val) {

  this[key] = val;

};

Jedi.prototype.get = function(key) {

  return this[key];

};

[↑]

Constructors

First, have a REALLY good reason for using a Constructor (be able to defend why it's the best option)

Assign methods to the prototype object, instead of overwriting the prototype with a new object. Overwriting the prototype makes inheritance impossible: by resetting the prototype you'll overwrite the base!

function Jedi() {

  console.log('new jedi');

}

// bad
Jedi.prototype = {

  fight: function fight() {

    console.log('fighting');

  },

  block: function block() {

    console.log('blocking');

  }
};

// good
Jedi.prototype.fight = function fight() {

  console.log('fighting');

};

Jedi.prototype.block = function block() {

  console.log('blocking');

};

Methods can return this to help with method chaining.

// bad
Jedi.prototype.jump = function() {

  this.jumping = true;
  return true;

};

Jedi.prototype.setHeight = function(height) {

  this.height = height;

};

var luke = new Jedi();
luke.jump(); // => true
luke.setHeight(20) // => undefined

// good
Jedi.prototype.jump = function() {

  this.jumping = true;
  return this;

};

Jedi.prototype.setHeight = function(height) {

  this.height = height;
  return this;

};

var luke = new Jedi();

luke.jump()
  .setHeight(20);

It's okay to write a custom toString() method, just make sure it works successfully and causes no side effects.

function Jedi(options) {

  options || (options = {});
  this.name = options.name || 'no name';

}

Jedi.prototype.getName = function getName() {

  return this.name;

};

Jedi.prototype.toString = function toString() {

  return 'Jedi - ' + this.getName();

};

[↑]

Modules

The module should start with a !. This ensures that if a malformed module forgets to include a final semicolon there aren't errors in production when the scripts get concatenated.
The file should be named with camelCase, live in a folder with the same name, and match the name of the single export.
Add a method called noConflict() that sets the exported module to the previous version and returns this one.

Always declare 'use strict'; at the top of the module.

// fancyInput/fancyInput.js

!function(global) {
  'use strict';

  var previousFancyInput = global.FancyInput;

  function FancyInput(options) {
    this.options = options || {};
  }

  FancyInput.noConflict = function noConflict() {
    global.FancyInput = previousFancyInput;
    return FancyInput;
  };

  global.FancyInput = FancyInput;
}(this);

[↑]

jQuery

Prefix jQuery object variables with a $.

// bad
var sidebar = $('.sidebar');

// good
var $sidebar = $('.sidebar');

Cache jQuery lookups.

// bad
function setSidebar () {

  $('.sidebar').hide();

  // ...stuff...

  $('.sidebar').css({

    'background-color': 'pink'

  });
}

// good
function setSidebar () {

  var $sidebar = $('.sidebar'),
      $this = this;

  $sidebar.hide();

  // ...stuff...

  $sidebar.css({

    'background-color': 'pink'

  });

}

For DOM queries use Cascading $('.sidebar ul') or parent > child $('.sidebar > .ul'). jsPerf

Use find with scoped jQuery object queries.

// bad
$('.sidebar', 'ul').hide();

// bad
$('.sidebar').find('ul').hide();

// good
$('.sidebar ul').hide();

// good
$('.sidebar > ul').hide();

// good (slower)
$sidebar.find('ul');

// good (faster)
$($sidebar[0]).find('ul');

[↑]

ECMAScript 5 Compatibility

Refer to Kangax's ES5 compatibility table

[↑]

Testing

Yup.
```
function() {

  return true;

}
```
[↑]

Performance

[↑]

Resources

Read This

Annotated ECMAScript 5.1

Other Styleguides

Other Styles

Naming this in nested functions - Christian Johansen
Conditional Callbacks

Books

JavaScript: The Good Parts - Douglas Crockford
JavaScript Patterns - Stoyan Stefanov
Pro JavaScript Design Patterns - Ross Harmes and Dustin Diaz
High Performance Web Sites: Essential Knowledge for Front-End Engineers - Steve Souders
Maintainable JavaScript - Nicholas C. Zakas
JavaScript Web Applications - Alex MacCaw
Pro JavaScript Techniques - John Resig
Smashing Node.js: JavaScript Everywhere - Guillermo Rauch

Blogs

[↑]

In the Wild

This is a list of organizations that are using this style guide. Send us a pull request or open an issue and we'll add you to the list.

Airbnb: airbnb/javascript
American Insitutes for Research: AIRAST/javascript
ExactTarget: ExactTarget/javascript
GoCardless: gocardless/javascript
GoodData: gooddata/gdc-js-style
How About We: howaboutwe/javascript
MinnPost: MinnPost/javascript
National Geographic: natgeo/javascript
Razorfish: razorfish/javascript-style-guide
Shutterfly: shutterfly/javascript

Translation

This style guide is also available in other languages:

🇩🇪 German: timofurrer/javascript-style-guide
🇯🇵 Japanese: mitsuruog/javacript-style-guide

The JavaScript Style Guide Guide

Reference

Contributors

View Contributors

[↑]

Name		Name	Last commit message	Last commit date
Latest commit History 127 Commits
linters/SublimeLinter		linters/SublimeLinter
.gitignore		.gitignore
README.md		README.md
sublime-text-config.txt		sublime-text-config.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Grasshopper JavaScript Style Guide() {

TL;DR

Table of Contents

Types

Objects

Arrays

Strings

Embedded HTML

Functions

Properties

Variables

Hoisting

Conditional Expressions & Equality

Blocks

Comments

Whitespace

Leading Commas

Semicolons

Type Casting & Coercion

Naming Conventions

Accessors

Constructors

Modules

jQuery

ECMAScript 5 Compatibility

Testing

Performance

Resources

In the Wild

Translation

The JavaScript Style Guide Guide

Contributors

};

About

Releases

Packages

koteshwerrao/javascript-styleguide

Folders and files

Latest commit

History

Repository files navigation

Grasshopper JavaScript Style Guide() {

TL;DR

};

About

Resources

Stars

Watchers

Forks