Buzz JS guide

guide.js

/*jshint undef:true, forin:false, eqeqeq:true, browser:true, newcap:true */
/*global console:true, $:true */
(function (global) { // We always pass global here

// Note: at the top of the file, we define things we are going to use more
// often in this file, like you would with CommonJS require or Python imports
var bm = global.bm,
    _ = bm.util,

    EventEmitter = global.EventEmitter2,
    AnotherClass = bm.AnotherClass;

// General stuff
// -------------
// - softtabs, 2 spaces
// - 2 whitelines between each function/method
// - jshint (see header) passing, always.
// - Lines are <= 80char


// utilFunctionA
// -------------
// Describe this here shortly. Note: util function that don't fit 
// in a class method, we put in here.
function utilFunctionA() {
  // ......
}


// MyClass < BaseClass
// -------------------
// Brief description of what this thing does.
// This, for example, takes a string and a Rainbow
// and makes an instance of a Unicorn
//
// The < in the title means that MyClass inherits from BaseClass
//
// + params
//    - someString (String) - a string with the unicorns name
//    - rainbow (Rainbow) - a Rainbow object
// + returns
//    - (Unicorn) - returns a new unicorn instance

function MyClass(name, rainbow) {
  // All variables are at the top of the function.
  var obj,
      elements,
      something,
      otherThingFromElement, // Rather a bit too verbose, than too short.
      value,
      x, l, el; // Unless it is really obvious

  // Initialize all properties inside the constructor, even when null
  this.counter = 0;
  this.title = null;

  // In case you want to be sure that all methods are always executed within
  // the scope of this instance, we do a bindAll. This is typically needed
  // when directly using instance methods as event handlers of DOM elements.
  _.bindAll(this);

  // Do stuff
  l = elements.length;
  for (x = 0; x < l; x++) {
    el = elements[x];
    if (something === el) { // Always triple ===

      // When something does not fit within 79 char, we break and
      // give a *double* indent, Python style.
      otherThingFromElement =
          something.getClassesTheFastestWayPossible(true, false, true);

      // We are not afraid of comments.
      value = x > 0 ? "a" : "b";
    }
  }

  if (true) {
    // ...
  } else if (true) {
    // ...
  } else {
    // ...
  }

  // When short and readable, chain on a single line
  $("body").remove().end().find();

  // When long or less readable, we can indent like this
  $("foo")
      .dsadas()
      .dasdsadas()
      .adasdasdas()
      .dasdasdas();
}

// Inheritance
_.inherits(MyClass, AnotherClass);


// ### Public MyClass :: myMethod
MyClass.prototype.myMethod = function(el) {
  // Often it is easy and clean to pass event handler like this
  $(el).click(this.handleSaveButton);
};


// ### Public MyClass :: myOtherMethod
MyClass.prototype.myOtherMethod = function(el) {
  var self = this;

  // But sometimes you might want to use self, and that is fine too,
  // as long as we choose the most readable option
  $(el).click(function() {
    $(this).removeClass('never-touched');
    self._updateInternalCounter();
  });
};


// ### Public MyClass :: handleSaveButton
// When a method is an event handler, we name methods like "handle<Something".
// This allows to directly el.click(this.handleSaveButton);
MyClass.prototype.handleSaveButton = function(e) {
  e.preventDefault();
};


// ### Private MyClass :: updateInternalCounter
// We mark methods as private with _. Methods are marked private only when they
// are really obviously private and default to public, to prevent having those
// underscores all over the place.
MyClass.prototype._updateInternalCounter = function() {
  this.counter++; // We are perfectly fine with ++
};


})(this); // Always pass this as global