JSCS – JavaScript Code Style

JSCS – JavaScript Code Style

As projects grow from small to medium, and eventually to large, small oversights can turn into big ones.  Couple that with a development team that increases in size (and experience) and things like code consistency, technical oversight and best practices become pivotal for long term success and maintainability.  In the last few years, JavaScript (as well as CoffeeScript and TypeScript) has grown increasingly popular — and not just for Web development.  Indeed, a good part of my project work, both front and backend, is now JavaScript based.

While the tooling, compatibility and support for JavaScript has immensely improved, the language itself has changed little.

One of the best things about JavaScript is that you can do just about anything.  One of the worst things about JavaScript is that you can do just about anything.

Numerous frameworks and patterns have emerged to help inject more structure and rigor to what is a very dynamic, functional language.  But like anything, there are no silver bullets…

After working on several large JavaScript projects that spanned multiple clients and 6+ developers, I quickly realized that despite all our tooling (JavaScript/CSS linting, file concatenation/minimization, etc.) the one thing we lacked was a good style guide and enforcer.

Enter JSCS – JavaScript Code Style.  JSCS is a code style linter that features an exhaustive list of rules that can be en/disabled, as well as a command line interface.  JSCS is available as an NPM module and easily installed via a good ‘ol `npm install`.  The JSCS Web site also allows you to dynamically evaluate sample rules files from industry heavy weights, including Google and jQuery, against your own javascript.  Our team ended up using the Airbnb rules file as a starting template.

After walking through the rules as a team and voting on what we felt best reflected what we wanted stylistically and was also in line with the industry in general.  The discussion was interactive and largely democratic; it was collaborative and helped promote a sense of team-wise buy-in and adoption, which is important.

For integrating team-wide policies like this, I have two basic rules:

  1. Adoption needs to be easy.  Stupid easy.  Tooling and automation should grease the wheels and make it easy for anyone on the team to run/use.
  2. If existing projects/files need to be updated, there needs to be a good, automated way of doing so.  No one wants to sign up for frivolous legacy clean-up work.

Spoiler alert: JSCS (with some paired tooling…) checks both boxes beautifully.  For the best part, read on…

Once the rule set was established, we had a number of existing projects and files that were non-compliant.  Although not readily apparent in the JSCS documentation, the CLI includes a -x option that amazing will auto format your files to be compliant with a given rule set!  Woo hoo!  Sure enough, most source was made compliant simply by running:

jscs src/web/js/**/*.js -x

Disclaimer: not all rules can simply be updated/fixed by JSCS – some simply need to be fixed manually.  As an an example, a project that had 903 style defects came down to 45 that needed to be manually updated.

Last but not least, we tie this into our build via grunt-jscs.  Likewise, there’s a gulp plugin as well.  Stylistic failures will fail the main build task, initiated during any PR/integration build.  Likewise, WebStorm and Sublime – the two most popular IDEs used on our team – can show style violations inline, as you add and edit code.

Now we have consistent, enforced code styles, making life easier as developer go between different projects (or new developers are added), as well as conforming to general JavaScript best practices.  Likewise, the tooling and automation makes this very easy to integrate and run, for anyone.  Win-win, with very little skin off our back.

One final note: consistent coding standards are great.  Stuffy or overly restrictive rules, particularly for a language like JavaScript, can be self defeating.  Enforcing coding styles may make code consistent, and thus help curb defects, but 100% stylistically compliant code doesn’t mean defect free code or an awesome user experience.  Like any tool, apply it judiciously, for the right reasons.

Happy coding!

Leave Reply