Top Related Projects
JavaScript Style Guide
:bathtub: Clean Code concepts adapted for JavaScript
🌟 JavaScript Style Guide, with linter & automatic code fixer
Style guides for Google-originated open-source projects
:art: A JavaScript Quality Guide
Standards for developing consistent, flexible, and sustainable HTML and CSS.
Quick Overview
Idiomatic.js is a comprehensive style guide for writing JavaScript code. It provides a set of principles and best practices for maintaining consistent, readable, and efficient JavaScript across projects and teams. The repository serves as a collaborative effort to establish coding standards in the JavaScript community.
Pros
- Promotes code consistency and readability across projects and teams
- Covers a wide range of JavaScript coding practices and patterns
- Regularly updated to reflect modern JavaScript features and best practices
- Widely recognized and adopted in the JavaScript community
Cons
- Some guidelines may be subjective and open to debate
- Strict adherence to all rules may sometimes conflict with project-specific requirements
- Can be overwhelming for beginners due to the extensive list of guidelines
- May require significant effort to implement in existing large-scale projects
Code Examples
This project is not a code library, but rather a style guide. Therefore, code examples are not applicable in this context.
Getting Started
As this is a style guide and not a code library, there are no specific installation or setup instructions. To start using the Idiomatic.js style guide in your projects:
- Visit the Idiomatic.js GitHub repository
- Read through the style guide documentation
- Consider adopting the guidelines in your JavaScript projects
- Optionally, integrate the style guide with your team's coding standards
- Use linting tools like ESLint to enforce the style guide automatically in your development workflow
Competitor Comparisons
JavaScript Style Guide
Pros of javascript
- More comprehensive and detailed guide, covering a wider range of topics
- Regularly updated with modern JavaScript practices and ES6+ features
- Includes explanations and reasoning behind each rule, aiding understanding
Cons of javascript
- Can be overwhelming due to its extensive nature, especially for beginners
- Some rules may be opinionated and not universally accepted in all projects
- Requires more time to fully understand and implement all guidelines
Code Comparison
idiomatic.js:
var foo = function (bar) {
return bar++;
};
javascript:
const foo = (bar) => {
return bar + 1;
};
Key Differences
- javascript emphasizes use of
const
and arrow functions - idiomatic.js uses traditional function declarations and
var
- javascript tends to prefer more explicit operations (e.g.,
bar + 1
instead ofbar++
)
Both repositories aim to provide JavaScript style guides, but javascript offers a more comprehensive and modern approach. While idiomatic.js focuses on core principles, javascript covers a broader range of topics and is more frequently updated. The choice between them may depend on project requirements and team preferences.
:bathtub: Clean Code concepts adapted for JavaScript
Pros of clean-code-javascript
- More comprehensive coverage of JavaScript best practices
- Includes modern ES6+ syntax and features
- Provides detailed explanations and examples for each principle
Cons of clean-code-javascript
- Less focus on specific coding style conventions
- May be overwhelming for beginners due to its extensive content
- Some principles might be subjective or context-dependent
Code Comparison
idiomatic.js:
var foo = function (bar) {
return bar++;
};
clean-code-javascript:
function incrementAndReturn(number) {
return number + 1;
}
The clean-code-javascript example demonstrates:
- More descriptive function naming
- Clear parameter naming
- Avoiding side effects by not modifying the input
Both repositories aim to improve JavaScript code quality, but they approach it differently. idiomatic.js focuses more on consistent coding style and formatting, while clean-code-javascript emphasizes broader principles of clean, maintainable code. clean-code-javascript is more up-to-date with modern JavaScript practices, making it potentially more relevant for current projects. However, idiomatic.js may be more suitable for teams looking to establish a consistent coding style across their codebase.
Ultimately, both resources offer valuable insights for JavaScript developers, and combining principles from both can lead to high-quality, maintainable code.
🌟 JavaScript Style Guide, with linter & automatic code fixer
Pros of Standard
- Automated linting and formatting with minimal configuration
- Large ecosystem of plugins and integrations
- Active community and regular updates
Cons of Standard
- Less flexibility in customizing rules
- Opinionated style choices that may not suit all projects
- Steeper learning curve for newcomers to JavaScript
Code Comparison
Idiomatic.js:
var foo = function (bar) {
return bar++;
};
Standard:
function foo (bar) {
return bar++
}
Key Differences
- Standard enforces no semicolons, while Idiomatic.js recommends them
- Standard uses 2-space indentation, Idiomatic.js suggests 4 spaces
- Idiomatic.js provides more detailed explanations and rationales for its guidelines
- Standard focuses on automated enforcement, while Idiomatic.js is more of a style guide
Summary
Idiomatic.js offers a comprehensive style guide with explanations, suitable for learning and understanding JavaScript best practices. Standard provides an opinionated, automated approach to code style, emphasizing consistency and ease of use across projects. The choice between them depends on project requirements, team preferences, and the desired level of customization in coding style.
Style guides for Google-originated open-source projects
Pros of styleguide
- Covers multiple programming languages, not just JavaScript
- More comprehensive, addressing a wider range of coding scenarios
- Regularly updated and maintained by Google engineers
Cons of styleguide
- Less focused on JavaScript-specific best practices
- May be overly prescriptive for some developers or projects
- Can be overwhelming due to its extensive coverage
Code Comparison
idiomatic.js example:
var foo = {
bar: function() {
// ...
},
baz: function() {
// ...
}
};
styleguide example:
const foo = {
bar() {
// ...
},
baz() {
// ...
},
};
The styleguide example uses more modern JavaScript syntax with const
and concise method definitions, while idiomatic.js uses older var
and traditional function declarations.
Both repositories aim to provide coding style guidelines, but they differ in scope and focus. idiomatic.js is specifically tailored for JavaScript, offering detailed recommendations for writing clean and consistent JS code. styleguide, on the other hand, covers multiple languages and provides a broader set of guidelines for various aspects of software development at Google.
Developers should choose between these style guides based on their project requirements, team preferences, and the specific languages they're working with. While styleguide offers a more comprehensive approach, idiomatic.js might be more suitable for teams focused solely on JavaScript development.
:art: A JavaScript Quality Guide
Pros of js
- More comprehensive coverage of modern JavaScript features and best practices
- Includes sections on tooling, performance, and security
- Regularly updated with contributions from the community
Cons of js
- Less focused on specific coding style guidelines
- May be overwhelming for beginners due to its extensive content
- Some recommendations might be opinionated or controversial
Code Comparison
idiomatic.js:
var foo = {
bar: function() {
// ...
},
baz: function() {
// ...
}
};
js:
const foo = {
bar() {
// ...
},
baz() {
// ...
}
};
The js example uses modern ES6+ syntax with arrow functions and concise method definitions, while idiomatic.js follows a more traditional approach.
Summary
Both repositories aim to provide JavaScript best practices and style guides. idiomatic.js focuses more on specific coding conventions and formatting, while js offers a broader range of topics including modern JavaScript features, tooling, and performance optimization. The choice between the two depends on the developer's needs and preferences, with js being more suitable for those looking for a comprehensive guide to modern JavaScript development, and idiomatic.js for those seeking a more focused style guide.
Standards for developing consistent, flexible, and sustainable HTML and CSS.
Pros of Code Guide
- Covers a broader range of topics, including HTML and CSS best practices
- Provides more visual examples and illustrations
- Offers a cleaner, more modern design for easier readability
Cons of Code Guide
- Less detailed JavaScript-specific guidelines
- Fewer community contributions and updates
- Lacks extensive explanations for each recommendation
Code Comparison
Idiomatic.js:
var foo = function (bar) {
return bar++;
};
Code Guide:
var foo = function(bar) {
return bar++;
}
The differences are subtle, but Code Guide omits the space after the function keyword and before the opening parenthesis.
Summary
While Idiomatic.js focuses exclusively on JavaScript conventions with in-depth explanations, Code Guide offers a more comprehensive approach to front-end development standards. Code Guide covers HTML and CSS in addition to JavaScript, making it a more well-rounded resource for web developers. However, it lacks the depth and community involvement found in Idiomatic.js.
Idiomatic.js provides more detailed JavaScript-specific guidelines and benefits from active community contributions. On the other hand, Code Guide offers a cleaner, more visually appealing presentation of its content, which may be more accessible to beginners or those looking for quick reference.
Ultimately, the choice between these two style guides depends on the specific needs of the developer or team, with Idiomatic.js being more suitable for JavaScript-focused projects and Code Guide offering a broader perspective on front-end development practices.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
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.
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
- 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 or two spaces representing a real tab.
- If your editor supports it, always work with the "show invisibles" setting turned on. The benefits of this practice are:
- Enforced consistency
- Eliminating end of line whitespace
- Eliminating blank line whitespace
- Commits and diffs that are easier to read
- Use Editorconfig when possible. It supports most IDEs and handles most whitespace settings.
-
A. Parens, Braces, Linebreaks
// if/else/for/while/try always have spaces, braces and span multiple lines // this encourages readability // 2.A.1.1 // Examples of really cramped syntax if(condition) doSomething(); while(condition) iterating++; for(var i=0;i<100;i++) someIterativeFn(); // 2.A.1.1 // Use whitespace to promote readability if ( condition ) { // statements } while ( condition ) { // statements } for ( var i = 0; i < 100; i++ ) { // statements } // Even better: var i, length = 100; for ( i = 0; i < length; i++ ) { // statements } // Or... var i = 0, length = 100; for ( ; i < length; i++ ) { // statements } var prop; for ( prop in object ) { // statements } if ( true ) { // statements } else { // statements }
B. Assignments, Declarations, Functions ( Named, Expression, Constructor )
// 2.B.1.1 // Variables var foo = "bar", num = 1, undef; // Literal notations: var array = [], object = {}; // 2.B.1.2 // Using only one `var` per scope (function) or one `var` for each variable, // promotes readability and keeps your declaration list free of clutter. // Using one `var` per variable you can take more control of your versions // and makes it easier to reorder the lines. // One `var` per scope makes it easier to detect undeclared variables // that may become implied globals. // Choose better for your project and never mix them. // Bad var foo = "", bar = ""; var qux; // Good var foo = ""; var bar = ""; var qux; // or.. var foo = "", bar = "", qux; // or.. var // Comment on these foo = "", bar = "", quux; // 2.B.1.3 // var statements should always be in the beginning of their respective scope (function). // Bad function foo() { // some statements here var bar = "", qux; } // Good function foo() { var bar = "", qux; // all statements after the variables declarations. } // 2.B.1.4 // const and let, from ECMAScript 6, should likewise be at the top of their scope (block). // Bad function foo() { let foo, bar; if ( condition ) { bar = ""; // statements } } // Good function foo() { let foo; if ( condition ) { let bar = ""; // statements } }
// 2.B.2.1 // Named Function Declaration function foo( arg1, argN ) { } // Usage foo( arg1, argN ); // 2.B.2.2 // Named Function Declaration function square( number ) { return number * number; } // Usage square( 10 ); // Really contrived continuation passing style function square( number, callback ) { callback( number * number ); } square( 10, function( square ) { // callback statements }); // 2.B.2.3 // Function Expression var square = function( number ) { // Return something valuable and relevant return number * number; }; // Function Expression with Identifier // This preferred form has the added value of being // able to call itself and have an identity in stack traces: var factorial = function factorial( number ) { if ( number < 2 ) { return 1; } return number * factorial( number - 1 ); }; // 2.B.2.4 // Constructor Declaration function FooBar( options ) { this.options = options; } // Usage var fooBar = new FooBar({ a: "alpha" }); fooBar.options; // { a: "alpha" }
C. Exceptions, Slight Deviations
// 2.C.1.1 // Functions with callbacks foo(function() { // Note there is no extra space between the first paren // of the executing function call and the word "function" }); // Function accepting an array, no space foo([ "alpha", "beta" ]); // 2.C.1.2 // Function accepting an object, no space foo({ a: "alpha", b: "beta" }); // Single argument string literal, no space foo("bar"); // Expression parens, no space if ( !("foo" in obj) ) { obj = (obj.bar || defaults).baz; }
D. Consistency Always Wins
In sections 2.A-2.C, the whitespace rules are set forth as a recommendation with a simpler, higher purpose: consistency. It's important to note that formatting preferences, such as "inner whitespace" should be considered optional, but only one style should exist across the entire source of your project.
// 2.D.1.1 if (condition) { // statements } while (condition) { // statements } for (var i = 0; i < 100; i++) { // statements } if (true) { // statements } else { // statements }
E. Quotes
Whether you prefer single or double shouldn't matter, there is no difference in how JavaScript parses them. What ABSOLUTELY MUST be enforced is consistency. Never mix quotes in the same project. Pick one style and stick with it.
F. End of Lines and Empty Lines
Whitespace can ruin diffs and make changesets impossible to read. Consider incorporating a pre-commit hook that removes end-of-line whitespace and blanks spaces on empty lines automatically.
-
Type Checking (Courtesy jQuery Core Style Guidelines)
A. Actual Types
String:
typeof variable === "string"
Number:
typeof variable === "number"
Boolean:
typeof variable === "boolean"
Object:
typeof variable === "object"
Array:
Array.isArray( arrayLikeObject ) (wherever possible)
Node:
elem.nodeType === 1
null:
variable === null
null or undefined:
variable == null
undefined:
Global Variables:
typeof variable === "undefined"
Local Variables:
variable === undefined
Properties:
object.prop === undefined object.hasOwnProperty( prop ) "prop" in object
B. Coerced Types
Consider the implications of the following...
Given this HTML:
<input type="text" id="foo-input" value="1">
// 3.B.1.1 // `foo` has been declared with the value `0` and its type is `number` var foo = 0; // typeof foo; // "number" ... // Somewhere later in your code, you need to update `foo` // with a new value derived from an input element foo = document.getElementById("foo-input").value; // If you were to test `typeof foo` now, the result would be `string` // This means that if you had logic that tested `foo` like: if ( foo === 1 ) { importantTask(); } // `importantTask()` would never be evaluated, even though `foo` has a value of "1" // 3.B.1.2 // You can preempt issues by using smart coercion with unary + or - operators: foo = +document.getElementById("foo-input").value; // ^ unary + operator will convert its right side operand to a number // typeof foo; // "number" if ( foo === 1 ) { importantTask(); } // `importantTask()` will be called
Here are some common cases along with coercions:
// 3.B.2.1 var number = 1, string = "1", bool = false; number; // 1 number + ""; // "1" string; // "1" +string; // 1 +string++; // 1 string; // 2 bool; // false +bool; // 0 bool + ""; // "false"
// 3.B.2.2 var number = 1, string = "1", bool = true; string === number; // false string === number + ""; // true +string === number; // true bool === number; // false +bool === number; // true bool === string; // false bool === !!string; // true
// 3.B.2.3 var array = [ "a", "b", "c" ]; !!~array.indexOf("a"); // true !!~array.indexOf("b"); // true !!~array.indexOf("c"); // true !!~array.indexOf("d"); // false // Note that the above should be considered "unnecessarily clever" // Prefer the obvious approach of comparing the returned value of // indexOf, like: if ( array.indexOf( "a" ) >= 0 ) { // ... }
// 3.B.2.4 var num = 2.5; parseInt( num, 10 ); // is the same as... ~~num; num >> 0; num >>> 0; // All result in 2 // Keep in mind however, that negative numbers will be treated differently... var neg = -2.5; parseInt( neg, 10 ); // is the same as... ~~neg; neg >> 0; // All result in -2 // However... neg >>> 0; // Will result in 4294967294
-
// 4.1.1 // When only evaluating that an array has length, // instead of this: if ( array.length > 0 ) ... // ...evaluate truthiness, like this: if ( array.length ) ... // 4.1.2 // When only evaluating that an array is empty, // instead of this: if ( array.length === 0 ) ... // ...evaluate truthiness, like this: if ( !array.length ) ... // 4.1.3 // When only evaluating that a string is not empty, // instead of this: if ( string !== "" ) ... // ...evaluate truthiness, like this: if ( string ) ... // 4.1.4 // When only evaluating that a string _is_ empty, // instead of this: if ( string === "" ) ... // ...evaluate falsy-ness, like this: if ( !string ) ... // 4.1.5 // When only evaluating that a reference is true, // instead of this: if ( foo === true ) ... // ...evaluate like you mean it, take advantage of built in capabilities: if ( foo ) ... // 4.1.6 // When evaluating that a reference is false, // instead of this: if ( foo === false ) ... // ...use negation to coerce a true evaluation if ( !foo ) ... // ...Be careful, this will also match: 0, "", null, undefined, NaN // If you _MUST_ test for a boolean false, then use if ( foo === false ) ... // 4.1.7 // When only evaluating a ref that might be null or undefined, but NOT false, "" or 0, // instead of this: if ( foo === null || foo === undefined ) ... // ...take advantage of == type coercion, like this: if ( foo == null ) ... // Remember, using == will match a `null` to BOTH `null` and `undefined` // but not `false`, "" or 0 null == undefined
ALWAYS evaluate for the best, most accurate result - the above is a guideline, not a dogma.
// 4.2.1 // Type coercion and evaluation notes // Prefer `===` over `==` (unless the case requires loose type evaluation) // === does not coerce type, which means that: "1" === 1; // false // == does coerce type, which means that: "1" == 1; // true // 4.2.2 // Booleans, Truthies & Falsies // Booleans: true, false // Truthy: "foo", 1 // Falsy: "", 0, null, undefined, NaN, void 0
-
// 5.1.1 // A Practical Module (function( global ) { var Module = (function() { var data = "secret"; return { // This is some boolean property bool: true, // Some string value string: "a string", // An array property array: [ 1, 2, 3, 4 ], // An object property object: { lang: "en-Us" }, getData: function() { // get the current value of `data` return data; }, setData: function( value ) { // set the value of `data` and return it return ( data = value ); } }; })(); // Other things might happen here // expose our module to the global object global.Module = Module; })( this );
// 5.2.1 // A Practical Constructor (function( global ) { function Ctor( foo ) { this.foo = foo; return this; } Ctor.prototype.getFoo = function() { return this.foo; }; Ctor.prototype.setFoo = function( val ) { return ( this.foo = val ); }; // To call constructor's without `new`, you might do this: var ctor = function( foo ) { return new Ctor( foo ); }; // expose our constructor to the global object global.ctor = ctor; })( this );
-
A. You are not a human code compiler/compressor, so don't try to be one.
The following code is an example of egregious naming:
// 6.A.1.1 // Example of code with poor names function q(s) { return document.querySelectorAll(s); } var i,a=[],els=q("#foo"); for(i=0;i<els.length;i++){a.push(els[i]);}
Without a doubt, you've written code like this - hopefully that ends today.
Here's the same piece of logic, but with kinder, more thoughtful naming (and a readable structure):
// 6.A.2.1 // Example of code with improved names function query( selector ) { return document.querySelectorAll( selector ); } var idx = 0, elements = [], matches = query("#foo"), length = matches.length; for ( ; idx < length; idx++ ) { elements.push( matches[ idx ] ); }
A few additional naming pointers:
// 6.A.3.1 // Naming strings `dog` is a string // 6.A.3.2 // Naming arrays `dogs` is an array of `dog` strings // 6.A.3.3 // Naming functions, objects, instances, etc camelCase; function and var declarations // 6.A.3.4 // Naming constructors, prototypes, etc. PascalCase; constructor function // 6.A.3.5 // Naming regular expressions rDesc = //; // 6.A.3.6 // From the Google Closure Library Style Guide functionNamesLikeThis; variableNamesLikeThis; ConstructorNamesLikeThis; EnumNamesLikeThis; methodNamesLikeThis; SYMBOLIC_CONSTANTS_LIKE_THIS;
B. Faces of
this
Beyond the generally well known use cases of
call
andapply
, always prefer.bind( this )
or a functional equivalent, for creatingBoundFunction
definitions for later invocation. Only resort to aliasing when no preferable option is available.// 6.B.1 function Device( opts ) { this.value = null; // open an async stream, // this will be called continuously stream.read( opts.path, function( data ) { // Update this instance's current value // with the most recent value from the // data stream this.value = data; }.bind(this) ); // Throttle the frequency of events emitted from // this Device instance setInterval(function() { // Emit a throttled event this.emit("event"); }.bind(this), opts.freq || 100 ); } // Just pretend we've inherited EventEmitter ;)
When unavailable, functional equivalents to
.bind
exist in many modern JavaScript libraries.// 6.B.2 // eg. lodash/underscore, _.bind() function Device( opts ) { this.value = null; stream.read( opts.path, _.bind(function( data ) { this.value = data; }, this) ); setInterval(_.bind(function() { this.emit("event"); }, this), opts.freq || 100 ); } // eg. jQuery.proxy function Device( opts ) { this.value = null; stream.read( opts.path, jQuery.proxy(function( data ) { this.value = data; }, this) ); setInterval( jQuery.proxy(function() { this.emit("event"); }, this), opts.freq || 100 ); } // eg. dojo.hitch function Device( opts ) { this.value = null; stream.read( opts.path, dojo.hitch( this, function( data ) { this.value = data; }) ); setInterval( dojo.hitch( this, function() { this.emit("event"); }), opts.freq || 100 ); }
As a last resort, create an alias to
this
usingself
as an Identifier. This is extremely bug prone and should be avoided whenever possible.// 6.B.3 function Device( opts ) { var self = this; this.value = null; stream.read( opts.path, function( data ) { self.value = data; }); setInterval(function() { self.emit("event"); }, opts.freq || 100 ); }
C. Use
thisArg
Several prototype methods of ES 5.1 built-ins come with a special
thisArg
signature, which should be used whenever possible// 6.C.1 var obj; obj = { f: "foo", b: "bar", q: "qux" }; Object.keys( obj ).forEach(function( key ) { // |this| now refers to `obj` console.log( this[ key ] ); }, obj ); // <-- the last arg is `thisArg` // Prints... // "foo" // "bar" // "qux"
thisArg
can be used withArray.prototype.every
,Array.prototype.forEach
,Array.prototype.some
,Array.prototype.map
,Array.prototype.filter
-
This section will serve to illustrate ideas and concepts that should not be considered dogma, but instead exists to encourage questioning practices in an attempt to find better ways to do common JavaScript programming tasks.
A. Using
switch
should be avoided, modern method tracing will blacklist functions with switch statementsThere seems to be drastic improvements to the execution of
switch
statements in latest releases of Firefox and Chrome. http://jsperf.com/switch-vs-object-literal-vs-moduleNotable improvements can be witnessed here as well: https://github.com/rwldrn/idiomatic.js/issues/13
// 7.A.1.1 // An example switch statement switch( foo ) { case "alpha": alpha(); break; case "beta": beta(); break; default: // something to default to break; } // 7.A.1.2 // A alternate approach that supports composability and reusability is to // use an object to store "cases" and a function to delegate: var cases, delegator; // Example returns for illustration only. cases = { alpha: function() { // statements // a return return [ "Alpha", arguments.length ]; }, beta: function() { // statements // a return return [ "Beta", arguments.length ]; }, _default: function() { // statements // a return return [ "Default", arguments.length ]; } }; delegator = function() { var args, key, delegate; // Transform arguments list into an array args = [].slice.call( arguments ); // shift the case key from the arguments key = args.shift(); // Assign the default case handler delegate = cases._default; // Derive the method to delegate operation to if ( cases.hasOwnProperty( key ) ) { delegate = cases[ key ]; } // The scope arg could be set to something specific, // in this case, |null| will suffice return delegate.apply( null, args ); }; // 7.A.1.3 // Put the API in 7.A.1.2 to work: delegator( "alpha", 1, 2, 3, 4, 5 ); // [ "Alpha", 5 ] // Of course, the `case` key argument could easily be based // on some other arbitrary condition. var caseKey, someUserInput; // Possibly some kind of form input? someUserInput = 9; if ( someUserInput > 10 ) { caseKey = "alpha"; } else { caseKey = "beta"; } // or... caseKey = someUserInput > 10 ? "alpha" : "beta"; // And then... delegator( caseKey, someUserInput ); // [ "Beta", 1 ] // And of course... delegator(); // [ "Default", 0 ]
B. Early returns promote code readability with negligible performance difference
// 7.B.1.1 // Bad: function returnLate( foo ) { var ret; if ( foo ) { ret = "foo"; } else { ret = "quux"; } return ret; } // Good: function returnEarly( foo ) { if ( foo ) { return "foo"; } return "quux"; }
-
The basic principle here is:
Don't do stupid shit and everything will be ok.
To reinforce this concept, please watch the following presentation:
âEverything is Permitted: Extending Built-insâ by Andrew Dupont (JSConf2011, Portland, Oregon)
-
Single line above the code that is subject
Multiline is good
End of line comments are prohibited!
JSDoc style is good, but requires a significant time investment
-
Programs should be written in one language, whatever that language may be, as dictated by the maintainer or maintainers.
Appendix
Comma First.
Any project that cites this document as its base style guide will not accept comma first code formatting, unless explicitly specified otherwise by that project's author.
Principles of Writing Consistent, Idiomatic JavaScript by Rick Waldron and Contributors is licensed under a Creative Commons Attribution 3.0 Unported License.
Based on a work at github.com/rwldrn/idiomatic.js.
Top Related Projects
JavaScript Style Guide
:bathtub: Clean Code concepts adapted for JavaScript
🌟 JavaScript Style Guide, with linter & automatic code fixer
Style guides for Google-originated open-source projects
:art: A JavaScript Quality Guide
Standards for developing consistent, flexible, and sustainable HTML and CSS.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot