HubSpot JavaScript Style Guide() {

Forked from Airbnb's Style Guide

HubSpot's version of a mostly reasonable approach to JavaScript

Other Style Guides (from HubSpot)

• ES5
• React

Other Style Guides (from Airbnb)

• CSS & Sass
• Ruby

1. Types
2. References
3. Objects
4. Arrays
5. Destructuring
6. Strings
7. Functions
8. Arrow Functions
9. Constructors
10. Modules
11. Iterators and Generators
12. Properties
13. Variables
14. Hoisting
15. Comparison Operators & Equality
16. Blocks
17. Comments
18. Whitespace
19. Commas
20. Semicolons
21. Type Casting & Coercion
22. Naming Conventions
23. Accessors
24. Events
25. jQuery
26. ECMAScript 5 Compatibility
27. ECMAScript 6 Styles
28. Testing
29. HubSpot Variants
30. Performance
31. Resources
32. In the Wild
33. Translation
34. The JavaScript Style Guide Guide
35. Chat With Us About JavaScript
36. Contributors
37. License

• 1.1 Primitives: When you access a primitive type you work directly on its value.

  • string
  • number
  • boolean
  • null
  • undefined

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

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

  • object
  • array
  • function

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

⬆ back to top

• 2.1 Use const for all of your references; avoid using var. eslint: prefer-const, no-const-assign

  Why? This ensures that you can't reassign your references, which can lead to bugs and difficult to comprehend code.

  // bad
  var a = 1;
  var b = 2;
  
  // good
  const a = 1;
  const b = 2;

• 2.2 If you must reassign references, use let instead of var. eslint: no-var jscs: disallowVar

  Why? let is block-scoped rather than function-scoped like var.

  // bad
  var count = 1;
  if (true) {
    count += 1;
  }
  
  // good, use the let.
  let count = 1;
  if (true) {
    count += 1;
  }

• 2.3 Note that both let and const are block-scoped.

  // const and let only exist in the blocks they are defined in.
  {
    let a = 1;
    const b = 1;
  }
  console.log(a); // ReferenceError
  console.log(b); // ReferenceError

⬆ back to top

• 3.1 Use the literal syntax for object creation. eslint: no-new-object

  // bad
  const item = new Object();
  
  // good
  const item = {};

• 3.2 If your code will be executed in browsers in script context, don't use reserved words as keys. It won't work in IE8. More info. It’s OK to use them in ES6 modules and server-side code. jscs: disallowIdentifierNames

  // bad
  const superman = {
    default: { clark: 'kent' },
    private: true,
  };
  
  // good
  const superman = {
    defaults: { clark: 'kent' },
    hidden: true,
  };

• 3.3 Use readable synonyms in place of reserved words. jscs: disallowIdentifierNames

  // bad
  const superman = {
    class: 'alien',
  };
  
  // bad
  const superman = {
    klass: 'alien',
  };
  
  // good
  const superman = {
    type: 'alien',
  };

• 3.4 Use computed property names when creating objects with dynamic property names.

  Why? They allow you to define all the properties of an object in one place.

  function getKey(k) {
    return `a key named ${k}`;
  }
  
  // bad
  const obj = {
    id: 5,
    name: 'San Francisco',
  };
  obj[getKey('enabled')] = true;
  
  // good
  const obj = {
    id: 5,
    name: 'San Francisco',
    [getKey('enabled')]: true,
  };

• 3.5 Use object method shorthand. eslint: object-shorthand jscs: requireEnhancedObjectLiterals

  // bad
  const atom = {
    value: 1,
  
    addValue: function (value) {
      return atom.value + value;
    },
  };
  
  // good
  const atom = {
    value: 1,
  
    addValue(value) {
      return atom.value + value;
    },
  };

• 3.6 Use property value shorthand. eslint: object-shorthand jscs: requireEnhancedObjectLiterals

  Why? It is shorter to write and descriptive.

  const lukeSkywalker = 'Luke Skywalker';
  
  // bad
  const obj = {
    lukeSkywalker: lukeSkywalker,
  };
  
  // good
  const obj = {
    lukeSkywalker,
  };

• 3.7 Group your shorthand properties at the beginning of your object declaration.

  Why? It's easier to tell which properties are using the shorthand.

  const anakinSkywalker = 'Anakin Skywalker';
  const lukeSkywalker = 'Luke Skywalker';
  
  // bad
  const obj = {
    episodeOne: 1,
    twoJediWalkIntoACantina: 2,
    lukeSkywalker,
    episodeThree: 3,
    mayTheFourth: 4,
    anakinSkywalker,
  };
  
  // good
  const obj = {
    lukeSkywalker,
    anakinSkywalker,
    episodeOne: 1,
    twoJediWalkIntoACantina: 2,
    episodeThree: 3,
    mayTheFourth: 4,
  };

• 3.8 Only quote properties that are invalid identifiers. eslint: quote-props jscs: disallowQuotedKeysInObjects

Why? In general we consider it subjectively easier to read. It improves syntax highlighting, and is also more easily optimized by many JS engines.

// bad
const bad = {
  'foo': 3,
  'bar': 4,
  'data-blah': 5,
};

// good
const good = {
  foo: 3,
  bar: 4,
  'data-blah': 5,
};

• 3.9 Don't wrap object literals in extra parentheses except for arrow function returns

// bad
const bad = ({
  hello: 'world',
  foo: 'bar'
});

// good
const good = {
  hello: 'world',
  foo: 'bar'
};

// okay
const okay = () => ({
  hello: 'world',
  foo: 'bar'
});

⬆ back to top

• 4.1 Use the literal syntax for array creation. eslint: no-array-constructor

  // bad
  const items = new Array();
  
  // good
  const items = [];

• 4.2 Use Array#push instead of direct assignment to add items to an array.

  const someStack = [];
  
  // bad
  someStack[someStack.length] = 'abracadabra';
  
  // good
  someStack.push('abracadabra');

• 4.3 Use array spreads ... to copy arrays.

  // bad
  const len = items.length;
  const itemsCopy = [];
  let i;
  
  for (i = 0; i < len; i++) {
    itemsCopy[i] = items[i];
  }
  
  // good
  const itemsCopy = [...items];

• 4.4 To convert an array-like object to an array, use Array#from.

  const foo = document.querySelectorAll('.foo');
  const nodes = Array.from(foo);

• 4.5 Use return statements in array method callbacks. It's ok to omit the return if the function body consists of a single statement following 8.2. eslint: array-callback-return

  // good
  [1, 2, 3].map((x) => {
    const y = x + 1;
    return x * y;
  });
  
  // good
  [1, 2, 3].map(x => x + 1);
  
  // bad
  const flat = {};
  [[0, 1], [2, 3], [4, 5]].reduce((memo, item, index) => {
    const flatten = memo.concat(item);
    flat[index] = memo.concat(item);
  });
  
  // good
  const flat = {};
  [[0, 1], [2, 3], [4, 5]].reduce((memo, item, index) => {
    const flatten = memo.concat(item);
    flat[index] = flatten;
    return flatten;
  });
  
  // bad
  inbox.filter((msg) => {
    const { subject, author } = msg;
    if (subject === 'Mockingbird') {
      return author === 'Harper Lee';
    } else {
      return false;
    }
  });
  
  // good
  inbox.filter((msg) => {
    const { subject, author } = msg;
    if (subject === 'Mockingbird') {
      return author === 'Harper Lee';
    }
  
    return false;
  });

⬆ back to top

• 5.1 Use object destructuring when accessing and using multiple properties of an object. jscs: requireObjectDestructuring

  Why? Destructuring saves you from creating temporary references for those properties.

  // bad
  function getFullName(user) {
    const firstName = user.firstName;
    const lastName = user.lastName;
  
    return `${firstName} ${lastName}`;
  }
  
  // good
  function getFullName(user) {
    const { firstName, lastName } = user;
    return `${firstName} ${lastName}`;
  }
  
  // best
  function getFullName({ firstName, lastName }) {
    return `${firstName} ${lastName}`;
  }

• 5.2 Use array destructuring. jscs: requireArrayDestructuring

  const arr = [1, 2, 3, 4];
  
  // bad
  const first = arr[0];
  const second = arr[1];
  
  // good
  const [first, second] = arr;

• 5.3 Use object destructuring for multiple return values, not array destructuring. jscs: disallowArrayDestructuringReturn

  Why? You can add new properties over time or change the order of things without breaking call sites.

  // bad
  function processInput(input) {
    // then a miracle occurs
    return [left, right, top, bottom];
  }
  
  // the caller needs to think about the order of return data
  const [left, __, top] = processInput(input);
  
  // good
  function processInput(input) {
    // then a miracle occurs
    return { left, right, top, bottom };
  }
  
  // the caller selects only the data they need
  const { left, top } = processInput(input);

⬆ back to top

• 6.1 Use single quotes '' for strings. eslint: quotes jscs: validateQuoteMarks

  // bad
  const name = "Capt. Janeway";
  
  // good
  const name = 'Capt. Janeway';

• 6.2 Strings that cause the line to go over 100 characters should be written across multiple lines using string concatenation.

• 6.3 Note: If overused, long strings with concatenation could impact performance. jsPerf & Discussion.

  // bad
  const 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
  const 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
  const 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.';

• 6.4 When programmatically building up strings, use template strings instead of concatenation. eslint: prefer-template template-curly-spacing jscs: requireTemplateStrings

  Why? Template strings give you a readable, concise syntax with proper newlines and string interpolation features.

  // bad
  function sayHi(name) {
    return 'How are you, ' + name + '?';
  }
  
  // bad
  function sayHi(name) {
    return ['How are you, ', name, '?'].join();
  }
  
  // bad
  function sayHi(name) {
    return `How are you, ${ name }?`;
  }
  
  // good
  function sayHi(name) {
    return `How are you, ${name}?`;
  }

• 6.5 Never use eval() on a string, it opens too many vulnerabilities.

⬆ back to top

• 7.1 Use function declarations instead of function expressions. jscs: requireFunctionDeclarations

  Why? Function declarations are named, so they're easier to identify in call stacks. Also, the whole body of a function declaration is hoisted, whereas only the reference of a function expression is hoisted. This rule makes it possible to always use Arrow Functions in place of function expressions.

  // bad
  const foo = function () {
  };
  
  // good
  function foo() {
  }

• 7.2 Immediately invoked function expressions: eslint: wrap-iife jscs: requireParenthesesAroundIIFE

  Why? An immediately invoked function expression is a single unit - wrapping both it, and its invocation parens, in parens, cleanly expresses this. Note that in a world with modules everywhere, you almost never need an IIFE.

  // immediately-invoked function expression (IIFE)
  (function () {
    console.log('Welcome to the Internet. Please follow me.');
  }());

• 7.3 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. eslint: no-loop-func

• 7.4 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
  let test;
  if (currentUser) {
    test = () => {
      console.log('Yup.');
    };
  }

• 7.5 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...
  }

• 7.6 Never use arguments, opt to use rest syntax ... instead. prefer-rest-params

  Why? ... is explicit about which arguments you want pulled. Plus, rest arguments are a real Array, and not merely Array-like like arguments.

  // bad
  function concatenateAll() {
    const args = Array.prototype.slice.call(arguments);
    return args.join('');
  }
  
  // good
  function concatenateAll(...args) {
    return args.join('');
  }

• 7.7 Use default parameter syntax rather than mutating function arguments.

  // really bad
  function handleThings(opts) {
    // No! We shouldn't mutate function arguments.
    // Double bad: if opts is falsy it'll be set to an object which may
    // be what you want but it can introduce subtle bugs.
    opts = opts || {};
    // ...
  }
  
  // still bad
  function handleThings(opts) {
    if (opts === void 0) {
      opts = {};
    }
    // ...
  }
  
  // good
  function handleThings(opts = {}) {
    // ...
  }

• 7.8 Avoid side effects with default parameters.

  Why? They are confusing to reason about.

  var b = 1;
  // bad
  function count(a = b++) {
    console.log(a);
  }
  count();  // 1
  count();  // 2
  count(3); // 3
  count();  // 3

• 7.9 Always put default parameters last.

  // bad
  function handleThings(opts = {}, name) {
    // ...
  }
  
  // good
  function handleThings(name, opts = {}) {
    // ...
  }

• 7.10 Never use the Function constructor to create a new function.

  Why? Creating a function in this way evaluates a string similarly to eval(), which opens vulnerabilities.

  // bad
  var add = new Function('a', 'b', 'return a + b');
  
  // still bad
  var subtract = Function('a', 'b', 'return a - b');

• 7.11 Spacing in a function signature.

  Why? Consistency is good, and you shouldn’t have to add or remove a space when adding or removing a name.

  // bad
  const f = function(){};
  const g = function (){};
  const h = function() {};
  
  // good
  const x = function () {};
  const y = function a() {};

• 7.12 Never mutate parameters. eslint: no-param-reassign

  Why? Manipulating objects passed in as parameters can cause unwanted variable side effects in the original caller.

  // bad
  function f1(obj) {
    obj.key = 1;
  };
  
  // good
  function f2(obj) {
    const key = Object.prototype.hasOwnProperty.call(obj, 'key') ? obj.key : 1;
  };

• 7.13 Never reassign parameters. eslint: no-param-reassign

  Why? Reassigning parameters can lead to unexpected behavior, especially when accessing the arguments object. It can also cause optimization issues, especially in V8.

  // bad
  function f1(a) {
    a = 1;
  }
  
  function f2(a) {
    if (!a) { a = 1; }
  }
  
  // good
  function f3(a) {
    const b = a || 1;
  }
  
  function f4(a = 1) {
  }

⬆ back to top

• 8.1 When you must use function expressions (as when passing an anonymous function), use arrow function notation. eslint: prefer-arrow-callback, arrow-spacing jscs: requireArrowFunctions

  Why? It creates a version of the function that executes in the context of this, which is usually what you want, and is a more concise syntax.

  Why not? If you have a fairly complicated function, you might move that logic out into its own function declaration.

  // bad
  [1, 2, 3].map(function (x) {
    const y = x + 1;
    return x * y;
  });
  
  // good
  [1, 2, 3].map((x) => {
    const y = x + 1;
    return x * y;
  });

• 8.2 If the function body consists of a single expression, omit the braces and use the implicit return. Otherwise, keep the braces and use a return statement. eslint: arrow-parens, arrow-body-style jscs: disallowParenthesesAroundArrowParam, requireShorthandArrowFunctions

  Why? Syntactic sugar. It reads well when multiple functions are chained together.

  Why not? If you plan on returning an object.

  // bad
  [1, 2, 3].map(number => {
    const nextNumber = number + 1;
    `A string containing the ${nextNumber}.`;
  });
  
  // good
  [1, 2, 3].map(number => `A string containing the ${number}.`);
  
  // good
  [1, 2, 3].map((number) => {
    const nextNumber = number + 1;
    return `A string containing the ${nextNumber}.`;
  });

• 8.3 In case the expression spans over multiple lines, wrap it in parentheses for better readability.

  Why? It shows clearly where the function starts and ends.

  // bad
  [1, 2, 3].map(number => 'As time went by, the string containing the ' +
    `${number} became much longer. So we needed to break it over multiple ` +
    'lines.'
  );
  
  // good
  [1, 2, 3].map(number => (
    `As time went by, the string containing the ${number} became much ` +
    'longer. So we needed to break it over multiple lines.'
  ));

• 8.4 If your function takes a single argument and doesn’t use braces, omit the parentheses. Otherwise, always include parentheses around arguments. eslint: arrow-parens jscs: disallowParenthesesAroundArrowParam

  Why? Less visual clutter.

  // bad
  [1, 2, 3].map((x) => x * x);
  
  // good
  [1, 2, 3].map(x => x * x);
  
  // good
  [1, 2, 3].map(number => (
    `A long string with the ${number}. It’s so long that we’ve broken it ` +
    'over multiple lines!'
  ));
  
  // bad
  [1, 2, 3].map(x => {
    const y = x + 1;
    return x * y;
  });
  
  // good
  [1, 2, 3].map((x) => {
    const y = x + 1;
    return x * y;
  });

• 8.5 Avoid confusing arrow function syntax (=>) with comparison operators (<=, >=). eslint: no-confusing-arrow

  // bad
  const itemHeight = item => item.height > 256 ? item.largeSize : item.smallSize;
  
  // bad
  const itemHeight = (item) => item.height > 256 ? item.largeSize : item.smallSize;
  
  // good
  const itemHeight = (item) => { return item.height > 256 ? item.largeSize : item.smallSize; }

⬆ back to top

• 9.1 Always use class. Avoid manipulating prototype directly.

  Why? class syntax is more concise and easier to reason about.

  // bad
  function Queue(contents = []) {
    this.queue = [...contents];
  }
  Queue.prototype.pop = function () {
    const value = this.queue[0];
    this.queue.splice(0, 1);
    return value;
  };
  
  
  // good
  class Queue {
    constructor(contents = []) {
      this.queue = [...contents];
    }
    pop() {
      const value = this.queue[0];
      this.queue.splice(0, 1);
      return value;
    }
  }

• 9.2 Use extends for inheritance.

  Why? It is a built-in way to inherit prototype functionality without breaking instanceof.

  // bad
  const inherits = require('inherits');
  function PeekableQueue(contents) {
    Queue.apply(this, contents);
  }
  inherits(PeekableQueue, Queue);
  PeekableQueue.prototype.peek = function () {
    return this._queue[0];
  }
  
  // good
  class PeekableQueue extends Queue {
    peek() {
      return this._queue[0];
    }
  }

• 9.3 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;
  };
  
  const luke = new Jedi();
  luke.jump(); // => true
  luke.setHeight(20); // => undefined
  
  // good
  class Jedi {
    jump() {
      this.jumping = true;
      return this;
    }
  
    setHeight(height) {
      this.height = height;
      return this;
    }
  }
  
  const luke = new Jedi();
  
  luke.jump()
    .setHeight(20);

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

  class Jedi {
    constructor(options = {}) {
      this.name = options.name || 'no name';
    }
  
    getName() {
      return this.name;
    }
  
    toString() {
      return `Jedi - ${this.getName()}`;
    }
  }

• 9.5 Classes have a default constructor if one is not specified. An empty constructor function or one that just delegates to a parent class is unnecessary. no-useless-constructor

  // bad
  class Jedi {
    constructor() {}
  
    getName() {
      return this.name;
    }
  }
  
  // bad
  class Rey extends Jedi {
    constructor(...args) {
      super(...args);
    }
  }
  
  // good
  class Rey extends Jedi {
    constructor(...args) {
      super(...args);
      this.name = 'Rey';
    }
  }

⬆ back to top

• 10.1 Always use modules (import/export) over a non-standard module system. You can always transpile to your preferred module system.

  Why? Modules are the future, let's start using the future now.

  // bad
  const AirbnbStyleGuide = require('./AirbnbStyleGuide');
  module.exports = AirbnbStyleGuide.es6;
  
  // ok
  import AirbnbStyleGuide from './AirbnbStyleGuide';
  export default AirbnbStyleGuide.es6;
  
  // best
  import { es6 } from './AirbnbStyleGuide';
  export default es6;

• 10.2 Do not use wildcard imports.

  Why? This makes sure you have a single default export.

  // bad
  import * as AirbnbStyleGuide from './AirbnbStyleGuide';
  
  // good
  import AirbnbStyleGuide from './AirbnbStyleGuide';

• 10.3 And do not export directly from an import.

  Why? Although the one-liner is concise, having one clear way to import and one clear way to export makes things consistent.

  // bad
  // filename es6.js
  export { es6 as default } from './airbnbStyleGuide';
  
  // good
  // filename es6.js
  import { es6 } from './AirbnbStyleGuide';
  export default es6;

⬆ back to top

• 11.1 Don't use iterators. Prefer JavaScript's higher-order functions like map() and reduce() instead of loops like for-of. eslint: no-iterator

  Why? This enforces our immutable rule. Dealing with pure functions that return values is easier to reason about than side effects.