Skip to content

Contributing to postal.js

ifandelse edited this page May 10, 2014 · 2 revisions

Linting via JSHint

The postal.js repo includes .jshintrc and .jshintignore files to drive JSHint. If you want to contribute, we simply ask that you use an IDE that at least recognizes the .jshintrc file, OR (as an alternative) use the jshint npm module to lint the output on the command line.

Code Style Guide

We don't care about "bike-shedding" - these standards are simply in place to keep the project consistent internally:

###Tabs for Indentation, Spaces for Alignment We use tabs for indentation, equivalent to 4 spaces. You can set your IDE to 2-space-equivalent tabs if you like - we don't care. Just don't check in code formatted with spaces for indentation. However, after indenting we will use spaces for alignment (for example, we typically align the colons in object literals).

Other Spacing

  • Before opening parentheses for if, for, while, switch and catch. (We don't put spaces between the function name/expression and opening parens, just FYI.)
  • Around operators
  • Before left curly brace
  • Before else, while, catch and finally keywords
  • Inside parentheses for function declaration and call, if, while, for, switch and catch
  • Before and After the ? and : ternary operators
  • After any comma
  • Before and After any property name-value separator (i.e. - the :)

Braces

Curly braces always start on the SAME line. It's JavaScript, don't try to make it C# or Java - there are real language-level reasons why this is important.

New Lines (or Not)

  • else, catch and finally keywords should start on the same line as the preceding block's closing brace.
  • Ternary operators - unless very short - should have newlines after the ? and :.

In a nutshell, your code should look something like this (a la WebStorm's formatting example code):

foo(
	"demo",
	{
		title : "Demo",
		width : 100
	},
	function() {
		alert( "test" );
	}
);

function foo( x, y, z ) {
	bar( 1, b );
	var i = 0;
	var x = {0 : "zero", 1 : "one"};
	var foo = function() {
	}
	if ( !i > 10 ) {
		for ( var j = 0; j < 10; j++ ) {
			switch ( j ) {
				case 0:
					value = "zero";
				break;
				case 1:
					value = "one";
				break;
			}
			var c = j > 5 ? "GT 5" : "LE 5";
		}
	} else {
		var j = 0;
		try {
			while ( j < 10 ) {
				if ( i == j || j > 5 ) {
					a[j] = i + j * 12;
				}
				i = (j << 2) & 4;
				j++;
			}
			do {
				j--;
			} while ( j > 0 )
		} catch ( e ) {
			alert( "Failure: " + e.message );
		} finally {
			reset( a, i );
		}
	}
}

##TL;DR If we ask you to make any changes to your code formatting, please don't be upset. We love contribution! We just want to keep the project consistent and predictable on the mundane and boring things like code formatting so that our brain cycles get to focus on the fun and interesting problems we're trying to solve with libraries like postal.js!

Clone this wiki locally