This is a guide for writing consistent and aesthetically pleasing code at QbDVision, Inc. It is inspired by what is popular within the community, and flavored with some personal opinions.

This guide was originally created and forked from Felix Geisendörfer's Node.js Style Guide and is licensed under the CC BY-SA 3.0 license. Other companies are encouraged to fork this repository and make adjustments according to their preferences.

• 2 Spaces for indentation
• Newlines
• No trailing whitespace
• Use Semicolons
• 80 characters per line
• Use double quotes
• Opening braces go on the same line
• Declare one variable per let statement

• Use lowerCamelCase for variables, properties and function names
• Use UpperCamelCase for class names
• Use UPPERCASE for Constants
• HTML and CSS
• Filenames

• Never use var
• Object / Array creation

• Use the === operator
• Use descriptive conditions

• Write small functions
• Return early from functions
• Use the => syntax for nested closures
• Method chaining

• Use comments intelligently
• Use JsDoc syntax

• Object.preventExtensions, Object.seal, with, eval
• Requires At Top
• Getters and setters
• Do not extend built-in prototypes
• Use ES6 Syntax
• SQL

Use 2 spaces for indenting your code and swear an oath to never use tabs instead of spaces - a special kind of hell is awaiting you otherwise.

Use UNIX-style newlines (\n), and a newline character as the last character of a file. Windows-style newlines (\r\n) are forbidden inside any repository.

Just like you brush your teeth after every meal, you clean up any trailing whitespace in your JS files before committing. Otherwise the rotten smell of careless neglect will eventually drive away contributors and/or co-workers.

According to scientific research, the usage of semicolons is a core value of our community. Consider the points of the opposition, but be a traditionalist when it comes to abusing error correction mechanisms for cheap syntactic pleasures.

Limit your lines to 80 characters. Yes, screens have gotten much bigger over the last few years, but your brain has not. Use the additional room for split screen, your editor supports that, right?

Use double quotes, unless you are already inside of a string.

Right:

let foo = "bar";

Wrong:

let foo = 'bar';

Your opening braces go on the same line as the statement.

Right:

if (true) {
  console.log("winning");
}

Wrong:

if (true)
{
  console.log("losing");
}

Also, notice the use of whitespace before and after the condition statement.

Declare one variable per let statement, it makes it easier to re-order the lines. However, ignore [Crockford][crockfordconvention] when it comes to declaring variables deeper inside a function, just put the declarations wherever they make sense.

Right:

let keys   = ["foo", "bar"];
let values = [23, 42];

let object = {};
while (keys.length) {
  let key = keys.pop();
  object[key] = values.pop();
}

Wrong:

let keys = ["foo", "bar"],
    values = [23, 42],
    object = {},
    key;

while (keys.length) {
  key = keys.pop();
  object[key] = values.pop();
}

An exception to this rule is when pulling multiple variables out of an object. This is fine:

let {id, typeCode, data} = this.props;

Variables, properties and function names should use lowerCamelCase. They should also be descriptive. Single character variables and uncommon abbreviations should generally be avoided.

Right:

let adminUser = db.query("SELECT * FROM users ...");

Wrong:

let admin_user = db.query("SELECT * FROM users ...");

Class names should be capitalized using UpperCamelCase.

Right:

function BankAccount() {
}

Wrong:

function bank_Account() {
}

Constants should be declared as regular variables or static class properties, using all uppercase letters.

Right:

let SECOND = 1 * 1000;

function File() {
}
File.FULL_PERMISSIONS = 0777;

Wrong:

const SECOND = 1 * 1000;

function File() {
}
File.fullPermissions = 0777;

In HTML and CSS, use kebab case for class names and camel case for IDs. For example, in CSS you might see:

Right:

.this-is-a-class {
  //..
}

#thisIsAnId {
  //..
}

Wrong:

.thisIsAClass {
  //..
}

#this-Is-An-Id {
  //..
}

JS, JSX and SCSS filenames are snake case. For example:

snapshot_helper.js
some_thing.jsx
_bootstrap_overrides.scss

HTML and all other files are camel case. For example:

cannedReports.html
deployEnvironment.template

If it’s a Lambda function, name it *_handler.js. Otherwise name it after an appropriate design pattern. For example:

something_factory.js
this_other_facade.js

Directories are camel case (ex. webapp/controlMethods)

When naming booleans, use prefixes that give yes/no answers such as is, has, and does:

Good:

let isValid = true;

Bad:

let valid = true;  ← Bad

Never use var, always use let. Ex:

Right:

let a=2;

Wrong:

var a = 2;  ← Bad

Use trailing commas and put short declarations on a single line. Only quote keys when your interpreter complains:

Right:

let a = ["hello", "world"];
let b = {
  good: "code",
  "is generally": "pretty",
};

Wrong:

let a = [
  "hello", "world"
];
let b = {"good": "code"
        , is generally: "pretty"
        };

Programming is not about remembering stupid rules. Use the triple equality operator as it will work just as expected.

Right:

let a = 0;
if (a !== "") {
  console.log("winning");
}

Wrong:

let a = 0;
if (a == "") {
  console.log("losing");
}

Any non-trivial conditions should be assigned to a descriptively named variable or function:

Right:

let isValidPassword = password.length >= 4 && /^(?=.*\d).{4,}$/.test(password);

if (isValidPassword) {
  console.log("winning");
}

Wrong:

if (password.length >= 4 && /^(?=.*\d).{4,}$/.test(password)) {
  console.log("losing");
}

Keep your functions short. A good function fits on a slide that the people in the last row of a big room can comfortably read. So don't count on them having perfect vision and limit yourself to ~15 lines of code per function.

To avoid deep nesting of if-statements, always return a function's value as early as possible.

Right:

function isPercentage(val) {
  if (val < 0) {
    return false;
  }

  if (val > 100) {
    return false;
  }

  return true;
}

Wrong:

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:

function isPercentage(val) {
  let isInRange = (val >= 0 && val <= 100);
  return isInRange;
}

Use => syntax for nested closures. This is because it binds the this variable better.

Right:

req.on("end", () => {
  console.log("winning");
});

Wrong:

req.on("end", function() {
  console.log("losing");
});

// Also wrong:

req.on("end", function onEnd() {
  console.log("losing");
});

Don't add unnecessary brackets to closures.

Right:

let theThing = myArray.find(item => item.isThing === true);

Wrong:

let theThing = myArray.find((item) => item.isThing === true);

One method per line should be used if you want to chain methods.

You should also indent these methods so it's easier to tell they are part of the same chain.

Right:

User
  .findOne({ name: "foo" })
  .populate("bar")
  .exec(function(err, user) {
    return true;
  });

Wrong:

User
.findOne({ name: "foo" })
.populate("bar")
.exec(function(err, user) {
  return true;
});

User.findOne({ name: "foo" })
  .populate("bar")
  .exec(function(err, user) {
    return true;
  });

User.findOne({ name: "foo" }).populate("bar")
.exec(function(err, user) {
  return true;
});

User.findOne({ name: "foo" }).populate("bar")
  .exec(function(err, user) {
    return true;
  });

Use single or multi line comments. Try to write comments that explain higher level mechanisms or clarify difficult segments of your code. Don't use comments to restate trivial things.

Right:

// "ID_SOMETHING=VALUE" -> ["ID_SOMETHING=VALUE", "SOMETHING", "VALUE"]
let matches = item.match(/ID_([^\n]+)=([^\n]+)/);

/* This function has a nasty side effect where a failure to increment a
   redis counter used for statistics will cause an exception. This needs
   to be fixed in a later iteration. */
function loadUser(id, cb) {
  // ...
}

let isSessionValid = (session.expires < Date.now());
if (isSessionValid) {
  // ...
}

Wrong:

// Execute a regex
let matches = item.match(/ID_([^\n]+)=([^\n]+)/);

// Usage: loadUser(5, function() { ... })
function loadUser(id, cb) {
  // ...
}

// Check if the session is valid
let isSessionValid = (session.expires < Date.now());
// If the session is valid
if (isSessionValid) {
  // ...
}

When documenting methods and classes use JSDoc syntax.

Every JS file should have a comment at the top that explains the reason for this file existing. For example:

"use strict";

/* The functions here are responsible for ...
 */

Or if the file is for a class:

"use strict";

import //...

/**
 * This class is responsible for ...
 */
class SomeClass extends SomeOtherClass {

Crazy stuff that you will probably never need. Stay away from it.

Always put requires at top of file to clearly illustrate a file's dependencies. Besides giving an overview for others at a quick glance of dependencies and possible memory impact, it allows one to determine if they need a package.json file should they choose to use the file elsewhere.

Do not use setters, they cause more problems for people who try to use your software than they can solve.

Feel free to use getters that are free from side effects, like providing a length property for a collection class.

Do not extend the prototype of native JavaScript objects. Your future self will be forever grateful.

Right:

let a = [];
if (!a.length) {
  console.log("winning");
}

Wrong:

Array.prototype.empty = function() {
  return !this.length;
}

let a = [];
if (a.empty()) {
  console.log("losing");
}

Always use ES6 syntax.

For SQL, follow this style guide.