JavaScript Style Guide

JavaScript Style Guide to maintain readable code, that looks like it was written by one person, even if a whole team was working on it. Highly inspired by Airbnb JavaScript Style Guide

Table of contents

1. Tabs
2. Whitespace
3. Semicolons
4. Commas
5. Naming conventions
6. Variables
7. Objects
8. Accessors
9. Arrays
10. Strings
11. Events
12. Functions
13. Iterators
14. Type casting
15. Comparison Operators & Equality
16. Blocks
17. Comments
18. jQuery

Tabs

• 1.1 Use soft spaces instead of tabs.
• 1.2 Use an intendation of 2 spaces.

⬆ back to top

Whitespace

• 2.1 Place one space before the leading brace.

  var test = function() {};
  person.set('attr', {
      age: 21
  });

• 2.2 Place one space before the opening paranthesis in control statements (if, while etc.)

  if (person.name === 'John Doe') {}

• 2.3 Place no space before the argument list in function calls and declarations.

  var test = function(firstParameter) {};

• 2.4 Set off operators with spaces.

  var x = 1 + 2;

• 2.5 Use indentation when making long method chains. Use a leading dot, which emphasizes that the line is a method call, not a new statement.

  $('.items')
      .addClass('.additional-class')
      .attr('width', '110')
      .attr('height', '150')

⬆ back to top

Semicolons

• 3.1 Use them.

  var age = 21; //use semicolons

⬆ back to top

Commas

• 4.1 Use trailing commas.

  var numbers = [
      1,
      2,
      3,
  ]

• 4.2 Use additional trailing commas for the last elements in arrays.

  var numbers = [
      1,
      2,
      3, // additional trailing comma
  ]

⬆ back to top

Naming conventions

• 5.1 Use camelCase when naming objects, functions, variables, and instances.

  var firstName = 'John';
  var myObject = {};
  var testFunction = function() {};

• 5.2 Use SNAKE_CASE and uppercase for constants.

  var API_URL = '/api';

• 5.3 Use PascalCase when naming constructors or classes.

  function Person(options) {
      this.name = options.name;
  }
  var person = Person({
      name: 'John Doe'
  });

• 5.4 Use a leading underscore _ when naming private properties.

  this._firstName = 'John';

• 5.5 Don't use reserved words.

  // bad
  var default = 42;
  // good
  var defaultNumber = 42;

⬆ back to top

Variables

• 6.1 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.

  var name = 'John Doe';

• 6.2 Use one var per scope. Declare them at the top of their scope.

  var name = 'John Doe',
      age = '21',
      createPerson;
  createPerson = function(name, age) {
      var person,
          adult = 18;
      age = adult;
      person = new Person({
          name: name, 
          age:age
      });
      return person;
  };
  createPerson(name, age);

• 6.3 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.

  var name = 'John Doe',
      age = '21',
      createPerson;

⬆ back to top

Objects

• 7.1 Use the literal syntax for object creation.

  var person = {
      name: 'John Doe'
  };

• 7.2 Methods can return this to help with method chaining.

  Person.prototype.walk = function(meters) {
      console.log('I walked ${meters}m');
      return this;
  }:
  Person.prototype.jump = function() {
      console.log('I jumped very high');
      return this;
  };

  var person = new Person();
  person.walk().jump();

• 7.3 Use dot notation when accessing properties.

  var person = {
      name: 'John Doe'
  };
  var name = person.name;

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

  var person = {
      name: 'John Doe'
  },
  property = 'name';
  var name = person[property];

⬆ back to top

Accessors

• 8.1 Accessor functions for properties are not required.

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

  person.setAge(21);
  var age = person.getAge();

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

  if (person.hasCoffee()) {}
  if (person.isAlive()) {}

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

  function Person(options) {
      this.set('name', options.name);
  }
  Person.prototype.set = function(key, val) {
      this[key] = val;
  };
  Person.prototype.get = function(key) {
      return this[key];
  };

⬆ back to top

Arrays

• 9.1 Use the literal syntax for array creation.

  var persons = [];

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

  var persons = [];
  persons.push(person);

• 9.3 Use slice to copy arrays.

  var numbers = [4, 2];
  var numbersCopy = numbers.slice();

⬆ back to top

Strings

• 10.1 Use single quotes '' for strings.

  var name = 'John Doe';

• 10.2 Strings, whose length exceeds the maximum amount of characters per line and would extend beyond the Right Margin (100 characters), should be split up and written across multiple lines using string concatenation.

  var description = 'I'm a very long text and need to be written across multiple lines using string ' + 
    'concatenation.';

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

Functions

• 11.1 Use function expressions instead of function declarations.

  var createPerson = function() {};

• 11.2 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.

  // Don't do this!
  if (isTrue) {
      var createPerson = function() {};
  }

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

  var createPerson = function() {};

⬆ back to top

Events

• 12.1 When attaching data payloads to events (whether DOM events or something more proprietary like Backbone events), pass a hash instead of a raw value. This allows a subsequent contributor to add more data to the event payload without finding and updating every handler for the event.

  $(this).trigger('productBought', {
      productId: 42
  });
  $(this).on('productBought', function(e, data) {
      productId = data.productId;
  });

⬆ back to top

Iterators

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

  var numbers = [4, 2];
  numbers.forEach(function(num) {
      console.log(num);
  });

• 13.2 Note: Have browser compatibility in mind. (.map and .reduce are not supported on <= IE8)

⬆ back to top

Type Casting

• 14.1 Use String for strings.

  var stringValue = String(42);

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

  var intValue = parseInt('42', 11);

• 14.3 Use Boolean for booleans.

  var isTrue = Boolean(0);

⬆ back to top

Comparison Operators & Equality

• 15.1 Use === and !== over == and !=.

• 15.2 Note: Conditional statements such as the if statement evaluate their expression using coercion with the ToBoolean abstract 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 evaluate 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
    }

• 15.3 Use shortcuts.

• 15.4 Note: For more information see Truth Equality and JavaScript by Angus Croll.

⬆ back to top

Blocks

• 16.1 Use braces with all multi-line blocks.

  if (!age) return false; 
  // or
  if (!age) {
      return false;
  }
  // but NOT
  if (!age) { return false; }
  // or
  if (!age)
      return false;

• 16.2 If you're using multi-line blocks with if and else, put else on the same line as your if block's closing brace.

  if (age) {
      console.log('You have an age.');
  } else {
      console.log('Uups! Looks like you are an unborn');
  }

⬆ back to top

Comments

• 17.1 Use /** ... */ for multi-line comments. Include a description, specify types and values for all parameters and return values.

  /**
   * Create a new person.
   *
   * @param {string} name
   * @return {Person}
   */
   var createPerson = function(name) {
      return new Person({
          name: name
      });
   }

• 17.2 Note: For more information see JSDoc.

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

  console.log('Make pretty comments!');

  // Create a new person
  var person = new Person();

• 17.4 Use // FIXME: to annotate problems.

  // FIXME: Something is wrong here, please fix it

• 17.5 Use // TODO: to annotate solutions to problems.

  // TODO: Write more code!

⬆ back to top

jQuery

• 18.1 Cache jQuery lookups.

  var setSidebar = function() {
      var sidebar = $('.sidebar');
      sidebar.hide();
      sidebar.show();
  };

⬆ back to top