Balderdash node.js Project Guidelines

gistfile1.md

Setup

When setting up a new project, the following tasks are to be completed, in order, before writing any code:

1. Create a README file, and outline the basic purpose of the project
2. If not a Sails.js application, run npm init
3. Integrate CI (Travis-CI or CircleCI) with the project, and setup boilerplate mocha tests so that npm test doesn't fail.
4. Integrate with CodeClimate

Development Cadence

• if the module is proprietary, make sure private: true is set in package.json.
• commit early and often. code outside of source control is wrong.
• never push directly to master. Code that we can't easily revert by clicking a button in github is hazardous.
• every PR should have a well-defined purpose. Do not commit monolithic blobs.
• over-communicate with the team.

Syntax

Guidelines on how code should appear

• jshint should be integrated into CI
• Whitespace: Indent with 2 spaces, and use UNIX line endings
• Prefer lodash functions over native looping constructs
• Prefer context binding using .bind to manage context
• do not copy/paste code.

Semantics

Guidelines on how ideas and concepts should be expressed in code

General Functionality

• Do not re-invent the wheel. Search npmjs.org first.
• Some clues which indicate you might be re-inventing an existing wheel:
  • any code containing i++
  • non-trivial comparison logic (e.g., comparing Dates, object structure)
  • you think you are cleverly fixing a bug or feature omission in someone else's framework
• Do not override existing framework functionality in order to Make Stuff Happen.

Control Flow

• Do not nest functions
• Functions should do one thing, and they should be testable.
• Do not complexly nest if/else statements.
• prefer Promises over callbacks/async
• Do not use switch/case statements to evaluate an enum. Use a map instead, e.g.

function performAction (action) {
  var methodMap = {
      create: 'PUT',
      read: 'GET',
      update: 'PUT',
      delete: 'DELETE'
    },
    method = methodMap[action];
}

• Prefer guard clauses over nested conditionals. e.g.

// Preferred
function rickRoll() {
  if (giveYouUp() || letYouDown()) {
    return;
  }
  runAroundAndDesertYou();
}

// Not Preferred
function rickRoll() {
  if (!giveYouUp()) {
    if (!letYouDown()) {
      runAroundAndDesertYou();
    }
  }
}

Philosophy

Focus on building software, not writing it. The foremost concern of any system/software design is conceptual integrity. The most important feature of anything is correctness, but the only feature that ultimately matters is existence. Sleep is sometimes more productive than coding: know when to take a break. Don't over-learn from past experience: causality may exist, but it's often hard to pin down. Contribute to open-source for fun and profit.