Jimmy Breck-McKye

A lazy programmer

Some Basic Conventions for JavaScript Projects

Package structure

Separate out third party code into its own folder

It’s helpful to communicate that code is third party, so that readers can Google it, and so that would-be editors know not to mess with it.

Test directories should mirror production code directories

The package structure of the test directory should match the package structure of the source directory, even if that means a line of directories with only one child a piece. Tests should live in the same path relative to the test root as the production code does with its own src root. This makes tests trivial to find, but easy to exclude from production code during deployment and concatenation.

Example: If you’re testing /src/utils/caching/LocalStore.js, place your test in /spec/utils/caching/LocalStoreSpec.js.

Classes should be separated into files named after them

Rather than a single file named ‘vehicles.js’ that contains constructors for Car(), Bike() and Boat(), consider separating each ‘class’ into its own file (‘Car.js’, ‘Bike.js’, etcetera). This will make types much easier to find by filename and encourage developers to keep files small and focused. This is the approach Java uses, and I recommend following it.


Write units tests first, then comments, and then documentation

Well-written unit tests can do a great job of explaining how your application works, and unlike other forms of documentation, you know they’re always up to date for as long as the test suite passes. Unit tests have their own intrinsic value to your project, so using Karma or Mocha will allow you to add documentation and robustness to your project in tandem.

Use readmes for technical documentation rather than external files

Documentation in external files or on corporate intranets is hard to find and invariably falls out of date. Rely