Team Style Guide

This is based off of idiomatic.js originally written by Rick Waldron, but has been modified for my team's specific needs. It will be updated as need be.

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

As a team we agree to adhere to these guidelines when it is possible. We understand that coding in a similar style makes reading code significantly easier. In other words, we will strive to speak with same dialect, using the same idioms.

This document is a statement of our project's commitment to code style consistency, readability and maintainability.

Unit Tests

Projects must include unit tests. We use Jasmine and MockJax for out unit tests.

Table of Contents

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

---

The Style Guide

1. Whitespace

• Indent with spaces, not tabs
• Indents should be four spaces wide

2. Beautiful Syntax

   A. Parens, Braces, Linebreaks

   // if/else/for/while/try always have spaces, braces and span multiple lines
   // this encourages readability
   
   // Examples of really cramped syntax
   
   if(condition) doSomething();
   
   while(condition) iterating++;
   
   for(var i=0;i<100;i++) someIterativeFn();
   
   
   // 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 )

   // Variables
   var foo = "bar",
     num = 1,
     undef;
   
   // Literal notations:
   var array = [],
     object = {};
   
   
   // Using only one `var` per scope (function) promotes readability
   // and keeps your declaration list free of clutter (also saves a few keystrokes)
   
   // Bad
   var foo = "";
   var bar = "";
   var qux;
   
   // Good
   var foo = "",
     bar = "",
     qux;
   
   
   // 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.
   }

   // Named Function Declaration
   function foo( arg1, argN ) {
   
   }
   
   // Usage
   foo( arg1, argN );
   
   
   // 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
   });
   
   
   // 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 );
   };

   C. Exceptions, Slight Deviations

   // 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" ]);
   
   // Function accepting an object, no space
   foo({
     a: "alpha",
     b: "beta"
   });
   
   // Single argument string literal, no space
   foo("bar");
   
   // Inner grouping parens, no space
   if ( !("foo" in obj) ) {
   
   }

   D. Quotes

   Always use single quotes.

3. 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)
   
   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

4. Conditional Evaluation

   // When only evaluating that an array has length,
   // instead of this:
   if ( array.length > 0 ) ...
   
   // ...evaluate truthiness, like this:
   if ( array.length ) ...
   
   
   // When only evaluating that an array is empty,
   // instead of this:
   if ( array.length === 0 ) ...
   
   // ...evaluate truthiness, like this:
   if ( !array.length ) ...
   
   
   // When only evaluating that a string is not empty,
   // instead of this:
   if ( string !== "" ) ...
   
   // ...evaluate truthiness, like this:
   if ( string ) ...
   
   
   // When only evaluating that a string _is_ empty,
   // instead of this:
   if ( string === "" ) ...
   
   // ...evaluate falsy-ness, like this:
   if ( !string ) ...
   
   
   // 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 ) ...
   
   
   // 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 ) ...
   
   
   // 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.

5. Naming

   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:

   // 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):

   // 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:

   // Naming strings
   
   `dog` is a string
   
   
   // Naming arrays
   
   `dogs` is an array of `dog` strings
   
   
   // Naming functions, objects, instances, etc
   
   camelCase; function and var declarations
   
   
   // Naming constructors, prototypes, etc.
   
   PascalCase; constructor function
   
   
   // 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 and apply, always prefer .bind( this ) or a functional equivalent, for creating BoundFunction definitions for later invocation. Only resort to aliasing when no preferable option is available.

   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.

   // 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 );
   }

   As a last resort, create an alias to this using self as an Identifier. This is extremely bug prone and should be avoided whenever possible.

   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

   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 with Array.prototype.every, Array.prototype.forEach, Array.prototype.some, Array.prototype.map, Array.prototype.filter

6. Misc

   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 statements

   There 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-module

   Notable improvements can be witnessed here as well: rwaldron#13

   // An example switch statement
   
   switch( foo ) {
     case "alpha":
       alpha();
       break;
     case "beta":
       beta();
       break;
     default:
       // something to default to
       break;
   }
   
   // 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 );
   };
   
   // 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

   // 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";
   }

7. Native & Host Objects

   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)

   <iframe src="http://blip.tv/play/g_Mngr6LegI.html" width="480" height="346" frameborder="0" allowfullscreen></iframe>

   http://blip.tv/jsconf/jsconf2011-andrew-dupont-everything-is-permitted-extending-built-ins-5211542

8. Comments

Attempt to self document whenever possible

#### Single line above the code that is subject
#### Multiline is good
#### End of line comments are prohibited!

10. One Language Code

    Programs should be written in one language, whatever that language may be, as dictated by the maintainer or maintainers.

---

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.