Document, largely by example, HazDev team preferred coding style for JavaScript

A JS Coding Style Guide

This is a placeholder file to name the Gist.

ClassName.js

'use strict';
/**
 * This file demonstrates the structure of a Javascript class (or module)
 * implementation to be followed by HazDev. At a high level, the file is broken
 * into several major sections. Each section is labeled with a comment block
 * header to identify the section. Within a given section, methods/variables
 * are declared/defined in alphabetical order. While not all sections are
 * required for all implementations, each section that appears in an
 * implementing file should appear in the order as it does below. Sectioning
 * comment blocks are not required in actual class implementations but exist in
 * this file to help deliniate the sections more clearly.
 *
 * Between each section there are two blank lines. Between each method/variable
 * declaration group (in Section 5) there should be a single blank line. Between
 * each method/variable definition there should be a single blank line.
 *
 * Method/variable names should be camelCased with a leadingLowercase. Private
 * method/variable names should, by convention, be prefixed with an underscore
 * (_). Static method and variable names should be ALL_CAPITAL_UNDERCASE. Class
 * and module names should be CamelCased with LeadingUppercase.
 *
 * When requiring dependencies in the CommonJS style, the assigned variable name
 * should match the dependency name as close as possible. 
 *
 * Variable method names used in this template example are as such only to
 * re-inforce the "scope" of the variable/method. In general, Hungarian (or
 * similar) notation is not a convention used by HazDev.
 *
 * Additional coding styles and conventions not explicitly documented, but
 * otherwise demonstrated (by way of how the code within this file is written),
 * should be considered a guide to which you should try to adhere.
 *
 */


// ------------------------------------------------------------
// Section 1. CommonJS Dependencies
// ------------------------------------------------------------

var Extend = require('Extend'),
    ParentClassName = require('ParentClassName');


// ------------------------------------------------------------
// Section 2. Private static variable declarations/definitions
// ------------------------------------------------------------

// Default values to be used by constructor
var _DEFAULTS = {
  privateVarOne: true,
  privateVarTwo: 'string',

  publicVarOne: 1,
  publicVarTwo: []
};

var _PRIVATE_STATIC_VAR_ONE = 1;
var _PRIVATE_STATIC_VAR_TWO = 2;


// ------------------------------------------------------------
// Section 3. Public static variable declarations/definitions
// ------------------------------------------------------------

var PUBLIC_STATIC_VAR_ONE = true;
var PUBLIC_STATIC_VAR_TWO = false;


// ------------------------------------------------------------
// Section 4. Class Definition
// ------------------------------------------------------------

/**
 * Class: ClassName
 *
 * @param params {Object}
 *      Configuration options. See _DEFAULTS for more details.
 */
var ClassName = function (params) {
  // ----------------------------------------------------------
  // Section 5. Variable/method declarations
  // ----------------------------------------------------------

  var _this,
      _initialize,

      _privateVarOne,
      _privateVarTwo,

      // Note :: Public variables need not be declared since
      //         they are attached to _this object directly.

      _privateMethodOne,
      _privateMethodTwo,

      publicFinalMethodOne,
      publicFinalMethodTwo;

      // Note :: Public (non-final) methods need not be declared
      //         since they are attached to _this object directly.


  // ----------------------------------------------------------
  // Section 6. Variable/method declarations
  // ----------------------------------------------------------

  // Inherit from parent class
  _this = Object.create(ParentClassName());

  /**
   * @constructor
   *
   */
  _initialize = function () {
    // Enumerate each property expected to be given in params method
    params = Extend({}, _DEFAULTS, params);
    _privateVarOne = params.privateVarOne;
    _privateVarTwo = params.privateVarTwo;

    _this.publicVarOne = params.publicVarOne;
    _this.publicVarTwo = params.publicVarTwo;
    params = null;
  };


  // ----------------------------------------------------------
  // Section 7. Private method definitions
  // ----------------------------------------------------------

  /**
   * Explain, at a high level, what this function does.
   *
   * @param arg1 {String}
   *      Explain the expected value of arg1
   * @param arg1 {String}
   *      Explain the expected value of arg1
   *
   * @return {String}
   *      Explain what the expected return value of the call
   *      should be.
   */
  _privateMethodOne = function (args) {
    var _arg1 = args.arg1,
        _arg2 = args.arg2;

    // ... now do something with arg
    return _arg1 + _arg2;
  };

  /**
   * Explain, at a high level, what this function does.
   *
   * @return {Number}
   *      Explain what the expected return value of the call
   *      should be.
   */
  _privateMethodTwo = function () {
    return _PRIVATE_STATIC_VAR_ONE + _PRIVATE_STATIC_VAR_TWO;
  };


  // ----------------------------------------------------------
  // Section 8. Public final method deifnitions
  // ----------------------------------------------------------

  /**
   * Explain, at a high level, what this function does.
   *
   */
  publicFinalMethodOne = function () {
  };

  /**
   * Explain, at a high level, what this function does.
   *
   */
  publicFinalMethodTwo = function () {
  };

  // Expose public "final" methods as part of the API
  _this.publicFinalMethodOne = publicFinalMethodOne;
  _this.publicFinalMethodTwo = publicFinalMethodTwo;

  // ----------------------------------------------------------
  // Section 9. Public method definitions
  // ----------------------------------------------------------

  /**
   * Explain, at a high level, what this function does.
   *
   */
  _this.publicMethodOne = function () {
    // ... implement this method ...
  };

  /**
   * Explain, at a high level, what this function does.
   *
   */
  _this.publicMethodTwo = function () {
    // ... implement this method ...
  };


  // Always call the constructor
  _initialize();
  return _this;
};


// ----------------------------------------------------------
// Section 10. Expose the public API
// ----------------------------------------------------------

// Expose public static variables as part of the API
ClassName.PUBLIC_STATIC_VAR_ONE = PUBLIC_STATIC_VAR_ONE;
ClassName.PUBLIC_STATIC_VAR_TWO = PUBLIC_STATIC_VAR_TWO;

module.exports = ClassName;

commonjs-class.sublime-snippet

<snippet>
  <content><![CDATA[
'use strict';


// Default values to be used by constructor
var _DEFAULTS = {
  ${3: // ... some defaults ...}
};


/**
 * Class: ${1:ClassName}
 *
 * @param params {Object}
 *      Configuration options. See _DEFAULTS for more details.
 */
var ${1:ClassName} = function (params) {
  var _this,
      _initialize,
      ${3:/* ... some properties ... */};


  // Inherit from parent class
  _this = Object.create(${2:ParentClassName}());

  /**
   * @constructor
   *
   */
  _initialize = function () {
    // Enumerate each property expected to be given in params method
    // params = Extend({}, _DEFAULTS, params);
    ${4:// ... begin implementation ...}

    // Always set params to null at the end of _initialize method.
    params = null;
  };


  // Always call the constructor
  _initialize();
  return _this;
};


module.exports = ${1:ClassName};
]]></content>
  <tabTrigger>jsClass</tabTrigger>
  <scope>source.js</scope>
  <description>Stubs out a new CommonJS class definition</description>
</snippet>