Zeega Style Guide

Examples in JavaScript, but should be applied in other languages where applicable.

// 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) promotes readability
// and keeps your declaration list free of clutter (also saves a few keystrokes)

// Good
var foo = "",
    bar = "",
  	quux;

// 2.B.1.3
// var statements should always be in the beginning of their respective scope (function).
// Same goes for const and let from ECMAScript 6.

function foo() {
	var bar = "",
    	qux;

  	// all statements after the variables declarations.
}

// 2.B.2.1
// Named Function Declaration
function foo( arg1, argN ) {

}

// Usage
foo( arg1, argN );

// 2.B.2.3
// Function Expression
var square = function( number ) {
  	return number * number;
};

// 2.B.2.4
// Constructor Declaration - Pascal Case
function FooBar( options ) {
  	this.options = options;
}

// Usage
var fooBar = new FooBar({ 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");

// Inner grouping parens, no space
if ( !("foo" in obj) ) {

}

E. Quotes

 Always use single quotes

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

Conditional Evaluation

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

Practical Style

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

Naming

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

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

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 witnesses here as well: rwaldron/idiomatic.js#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";
}

Comments

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

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Zeega Style Guide

Table of Contents

Files

README.md

Latest commit

History

README.md

File metadata and controls

Zeega Style Guide

Table of Contents