June 18, 2015

Using JSCS to Achieve a Consistent Code Style Within Your Team

Tom Alexander Programming, Technology 0 Comments

The more people who open a window, the more fingerprints that are left behind. Coding in a team is largely the same. Like a fingerprint, each developer has their own unique style that can look vastly different than others. Although there are linting libraries that will catch some of these style discrepancies, it can be difficult to enforce the nitty details. If you can make a piece of code look like it was written by one person, it immediately becomes clearer and easier to read (assuming the developer can write clean code in the first place, but I digress).

Enter JSCS

JSCS is a code style linter for programmatically enforcing your style guide. Ever get irritated when one developer doesn’t put a space between the ending function parenthesis and the opening curly brace? Here’s your chance to enforce this and create a strict, enforceable style for you and your team to follow.

Installation

JSCS can be installed via npm.

npm install jscs -g

1	npm install jscs -g

Setup

Let’s create a .jscsrc file at the root of your project. This will be used to define rules that you’d like to enforce in your JS codebase.

vi .jscsrc

1	vi .jscsrc

{
    "disallowEmptyBlocks": true,
    "disallowMultipleSpaces": true,
    "maximumLineLength": 120,
    "requireDollarBeforejQueryAssignment": true,
    "requireMultipleVarDecl": true
}

{

"disallowEmptyBlocks": true,

"disallowMultipleSpaces": true,

"maximumLineLength": 120,

"requireDollarBeforejQueryAssignment": true,

"requireMultipleVarDecl": true

}

For simplicity, my .jscsrc file has just a few rule definitions. Here is the full list for your consideration in your project. The rules I have selected are:

disallowEmptyBlocks – Blocks must have code in them and cannot be empty
disallowMultipleSpaces – Disallows multiple indentation characters (tabs or spaces) between identifiers, keywords, and any other token
maximumLineLength – the max number of characters allowed on one line
requireDollarBeforeJQueryAssignment – requires that all variables assigned to jQuery objects be prefixed by dollar signs
requireMultipleVarDecl – Variables defined next to eachother should only be prefixed with one var declaration separated by commas

As you can see, having just a small subset of these rules can go a long way to writing consistent code in your project.

Running JSCS

After you have created your .jscsrc file, it’s time to run the style checker against your code. For the purposes of this tutorial, here’s a sample JS file that violates all of the rules above.

Create a new file (test.js)

var x = $('.test');
var y = "tom";

if (x === 0) {
} else {
    console.log("bad");
}

var  z = "two spaces";

var x = $('.test');

var y = "tom";

if (x === 0) {

} else {

console.log("bad");

}

var z = "two spaces";

Run the code style checker against it

cd /path/to/your/project
jscs test.js

1 2	cd /path/to/your/project jscs test.js

JSCS will output something like this:

jQuery identifiers must start with a $ at test.js :
     1 |var x = $('.test');
------------^
     2 |var y = "tom";
     3 |

Var declarations should be joined at test.js :
     1 |var x = $('.test');
     2 |var y = "tom";
--------^
     3 |
     4 |if (x === 0) {

Empty block found at test.js :
     3 |
     4 |if (x === 0) {
     5 |} else {
---------^
     6 |    console.log("bad");
     7 |}

at most 1 spaces required between var and z at test.js :
     7 |}
     8 |
     9 |var  z = "two spaces";var x = $('.test');
-----------^
    10 |
    11 |

5 code style errors found.

jQuery identifiers must start with a $ at test.js :

1 |var x = $('.test');

------------^

2 |var y = "tom";

3 |

Var declarations should be joined at test.js :

1 |var x = $('.test');

2 |var y = "tom";

--------^

3 |

4 |if (x === 0) {

Empty block found at test.js :

3 |

4 |if (x === 0) {

5 |} else {

---------^

6 | console.log("bad");

7 |}

at most 1 spaces required between var and z at test.js :

7 |}

8 |

9 |var z = "two spaces";var x = $('.test');

-----------^

10 |

11 |

5 code style errors found.

Bonus: Fixing the issues automatically

One of the coolest features of JSCS is the ability to automatically fix *some* of the linting errors it encounters (Currently whitespace rules, EOF rule, and validateIndentation). This is especially good if you’re incorporating this into an existing codebase.

The command is simple:

jscs test.js --fix

1	jscs test.js --fix

Bonus 2: Parse ES6 code

It’s not perfect (yet), but it does a pretty good job of parsing against ES6 code as well.

jscs test.js --esnext

1	jscs test.js --esnext

Bonus 3: Create your own rules

Don’t see a rule that you’d like to enforce? Create it yourself! Here is the API.

This is just a brief intro to the power of this library. I will write a follow-up tutorial that will show you how to incorporate this into your workflow using Gulp and your IDE.

Thomas R Alexander