Principles of Writing Consistent, Idiomatic JavaScript

This is a living document and new ideas for improving the code around us are always welcome. Contribute: fork, clone, branch, commit, push, pull request.

• Rick Waldron @rwaldron, github
• Mathias Bynens @mathias, github
• Schalk Neethling @ossreleasefeed, github
• Kit Cambridge @kitcambridge, github
• Raynos github
• Matias Arriola @MatiasArriola, github
• John Fischer @jfroffice, github
• Idan Gazit @idangazit, github
• Leo Balter @leobalter, github
• Breno Oliveira @garu_rj, github
• Leo Beto Souza @leobetosouza, github
• Ryuichi Okumura @okuryu, github
• Pascal Precht @PascalPrecht, github
• EngForDev engfordev - Hwan Min Hong / MinTaek Kwon @leoinsight / Tw Shim @marocchino, github / Nassol Kim @nassol99, github / Juntai Park @rkJun, github / Minkyu Shim / Gangmin Won / Justin Yoo @justinchronicle / Daeyup Lee
• Marco Trulla @marcotrulla, github
• Alex Navasardyan @alexnavasardyan, github
• Mihai Paun @mihaipaun, github
• Evgeny Mandrikov @_godin_, github
• Sofish Lin @sofish, github
• Дејан Димић @dejan_dimic, github
• Miloš Gavrilović @gavrisimo, github
• Firede @firede github
• monkadd github
• Stephan Lindauer @stephanlindauer, github
• Thomas P @dragon5689 github
• Yotam Ofek @yotamofek github
• Aleksandr Filatov @greybax, github
• Duc Nguyen @ducntq, github
• James Young @jamsyoung, github
• Hao-Wei Jeng @l0ckys, github
• Richard Gibson @gibson042, github
• Fesuy github
• Stephane Moreau github
• Boris Nekezov github
• Akshat Joshi @akshat_joshi, github

All code in any code-base should look like a single person typed it, no matter how many people contributed.

The following list outlines the practices that I use in all code that I am the original author of; contributions to projects that I have created should follow these guidelines.

I do not intend to impose my style preferences on other people's code or projects; if an existing common style exists, it should be respected.

"Arguments over style are pointless. There should be a style guide, and you should follow it"

Rebecca Murphey

 

"Part of being a good steward to a successful project is realizing that writing code for yourself is a Bad Idea™. If thousands of people are using your code, then write your code for maximum clarity, not your personal preference of how to get clever within the spec."

Idan Gazit

Translations

• Bulgarian
• German
• French
• Spanish
• Portuguese - Brazil
• Korean
• 日本語
• Italian
• Russian
• Romanian
• 简体中文
• Serbian - cyrilic alphabet
• Serbian - latin alphabet
• 繁體中文
• Indonesian
• Greek
• Hindi

Important, Non-Idiomatic Stuff:

Code Quality Tools, Resources & References

• SonarQube
• Plato
• jsPerf
• jsFiddle
• Codepen
• jsbin
• JavaScript Lint (JSL)
• jshint
• jslint
• eslint
• jscs
• jscodesniffer
• Editorconfig
• Hound

Get Smart

Annotated ECMAScript 5.1

EcmaScript Language Specification, 5.1 Edition

The following should be considered 1) incomplete, and 2) REQUIRED READING. I don't always agree with the style written by the authors below, but one thing is certain: They are consistent. Furthermore, these are authorities on the language.

• Baseline For Front End Developers: 2015
• Eloquent JavaScript
• JavaScript, JavaScript
• Adventures in JavaScript Development
• Perfection Kills
• Douglas Crockford's Wrrrld Wide Web
• JS Assessment

Build & Deployment Process

Projects should always attempt to include some generic means by which source can be linted, tested and compressed in preparation for production use. For this task, grunt by Ben Alman is second to none and has officially replaced the "kits/" directory of this repo.

Test Facility

Projects must include some form of unit, reference, implementation or functional testing. Use case demos DO NOT QUALIFY as "tests". The following is a list of test frameworks, none of which are endorsed more than the other.

• QUnit
• Jasmine
• Vows
• Mocha
• Hiro
• JsTestDriver
• Buster.js
• Sinon.js
• Tape
• Jest

Table of Contents

• Whitespace
• Beautiful Syntax
• Type Checking (Courtesy jQuery Core Style Guidelines)
• Conditional Evaluation
• Practical Style
• Naming
• Misc
• Native & Host Objects
• Comments
• One Language Code

---

Preface

The following sections outline a reasonable style guide for modern JavaScript development and are not meant to be prescriptive. The most important take-away is the law of code style consistency. Whatever you choose as the style for your project should be considered law. Link to this document as a statement of your project's commitment to code style consistency, readability and maintainability.

Idiomatic Style Manifesto

1. <a name="whitespace">Whitespace</a>

• Never mix spaces and tabs.
• When beginning a project, before you write any code, choose between soft indents (spaces) or real tabs, consider this law.
  • For readability, I always recommend setting your editor's indent size to two characters — this means two spaces