Contributor Guidelines

This guide is a brief reference to how code should be written for CryptocoinJS. This applies to members and contributors.

Principles

1. People matter more than code. Optimize for people.
2. Write code for humans to read. It's easier to write code than to read code. Avoid verbosity, but don't be overly terse.
3. Code is the enemy. Lines of code should be reduced as much as possible. The best code is no code at all and Size is the enemy. This is probably the most important principle.
4. Organize according to the UNIX philosophy: small and simple modules that do one thing well. Take into consideration the Single Responsibility Principle
5. All code in this project should look like one person wrote it. We have a lot of work in this area.
6. Code should be documented (not auto-generated). But it should not be "documented" in the actual code. Documentation should emphasize usage examples and not so much API interface signatures. It's not that API docs are bad, they should just be made lower priority when compared to usage examples.
7. Tests should be implemented. Working code and tests are far more important than documentation.

Effective JavaScript

Compatibility

We are not interested in supporting legacy browsers. ES5 target should be satisfactory. This pretty much includes all modern browsers and > IE9.

Indentation

Two Spaces

Two spaces. No negotiation on this one.

console.log('indent demo');
if (true) {
  console.log('indent 1');
  if (true) {
    console.log('indent two');
  }	
}

Minimize Indentation Levels / Early Returns Encouraged

Early returns can increase readability. Remember principle #3?

Don't do this:

fs.readFile('/no/way/jose.txt', function(err, file) {
  if (err) {
    console.error(err);	
  } else {
    //do something else	
  }
});

Do this instead (if possible):

fs.readFile('/no/way/jose.txt', function(err, file) {
  if (err) return console.error(err);
  //do something else	
});

Semicolons

Gotta have them. I hate them and think that they're superfluous. If it's good enough for the maintainer of Node.js (Isaac S), Thomas Fuchs, and Jacob Thorton (Fat) creator of Bootstrap to skip them, then so should you. HOWEVER, it's the predominant opinion of the JavaScript community that you should use them and to write code in a team, you should probably use them. So, we'll use them here too unless we can get agreement of everyone not to use them - I don't see that happening.

Further reading:

• http://wordsbyf.at/2011/10/31/i-dont-write-javascript/
• http://dailyjs.com/2012/04/19/semicolons/
• http://blog.izs.me/post/2353458699/an-open-letter-to-javascript-leaders-regarding
• http://inimino.org/~inimino/blog/javascript_semicolons

Naming

(straight from Google's reference, except for the caveat on file names)

In general, use functionNamesLikeThis, variableNamesLikeThis, ClassNamesLikeThis, EnumNamesLikeThis, methodNamesLikeThis, CONSTANT_VALUES_LIKE_THIS, foo.namespaceNamesLikeThis.bar, and filenameslikethis.js. If you need to break up a long file name, use - and not _ or different cases.

Comments

It's more important to comment why something was done than to comment what is done. If you have to comment what the code does, it may not be clear enough. Don't go overboard though with Java style verbosity.

JSDoc is not acceptable. It completely violates principle #3 and just adds noise. Generating documentation from code is lazy practice and poor behavior.

Parenthesis, Commas, and Spaces

No spacing before or after parenthesis. Spaces after commas in methods.

Don't do this:

//NO
someFunc( 10, 20 );

//NO
function someFunc ( n, m ) {
  console.log( 'too many spaces' );
}

Do this:

//NO
someFunc(10, 20);

//NO
function someFunc(n, m) {
  console.log( 'too many spaces' );
}

Type Coercion

Terse code is encouraged IF its behavior is well defined. For example:

Prefer === and !==. Only use == and != where it makes sense.

null/undefined:

//this is good
function something(input) {
  if (input == null) { //this is acceptable terse way to check for `null` and `undefined`
    //do something
  }
}

typeof:

//typeof always returns a string, no need for ===
if (typeof val == 'string') //this is good

float:

var num = +'3433.22'; //this is acceptable as it's well known
num = parseFloat('3433.22'); //<--- probably preferred

var num2 = +'343.22 hi'; //be careful though, NaN
num2 = '343.22 hi'; //expected, 343.22

integer:

var num = ~~'3433.22'; //this is acceptable as well
num = parseInt('3433.22', 10); //<-- preferred

bool:

var b = !!'4'; //true
var c = !!'0'; //false

Quotes

Prefer ' instead of ". This makes it easier to embed HTML. The obvious exception is that if your string needs to actually contain ' character.

Properties

Do not use setFoo and getFoo notation. Leverage ES5 properties.

Other JavaScript Style Guides

These other guides are very popular. They differ slightly.

1. https://github.com/airbnb/javascript
2. http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml
3. https://github.com/rwaldron/idiomatic.js

Licensing

By contributing, you implicitly agree that all code that you contribute will be licensed under MIT. The only exception to this rule is that if you leverage a 3rd party library that is licensed in some other manner. Examples: code from CryptoJS, Stanford JavaScript Library, etc.

Living Document

The goal is to try to encourage code that's generally accepted by most JavaScript developers as clean and readable. As such, I will have no doubt made some mistakes and boneheaded decisions here. If it makes sense to change any of these rules, let's discuss. This document may be subject to change.