Javascript 👾

Linting
Formatting
Naming
Project Structure
- JS-only Applications
- Front-end JS
Documentation

We consider ourselves JS framework agnostic as we do not have a framework of preference. For some applications, not having a framework but instead using only ES 5/6 is the right choice, while in other cases React JS or Vue.JS are brought into the application stack.

Linting

We use and maintain our own ESLint shareable config for automated code checks conforming to our syntax conventions.

Formatting

Use soft-tabs with a two-space indent.
Prefer single quotes.

// Bad
let string = "String";

// Good
let string = 'String';

Use semicolons at the end of each statement.

// Bad
let string = 'String'

// Good
let string = 'String';

Use strict equality checks (=== and !==) except when comparing against (null or undefined).

// Bad
string == 'String'

// Good
string === 'String';

Use a trailing comma after each item in a multi-line array or object literal, except for the last item.

// Bad
{
  a: 'a',
  b: 'b',
}

// Good
{
  a: 'a',
  b: 'b'
}

Prefer ES6 classes over prototypes.

// Bad
function Animal() { }

Animal.prototype.speak = function() {
  return this;
}
 
// Good
class Animal { 
  speak() {
    return this;
  }
}

When you must use function expressions (as when passing an anonymous function), use the arrow function notation.

// Base class
class Request {
  function fetch() {}
}

// Bad
let records = Request.fetch().then(function() { })

// Good
let records = Request.fetch().then(() => { ... })

Prefer template strings over string concatenation.

// Bad
'string text' + expression + 'string text'

// Good
`string text ${expression} string text`

Prefer array functions like map and forEach over for loops.

// Bad
for (var index = 0; index < myArray.length; index++) {
  console.log(myArray[index]);
}

// Good
myArray.forEach(function (value) {
  console.log(value);
});

Use const for declaring variables that will never be re-assigned, and let otherwise.

Naming

Use lowerCamelCase for file names.

// Bad
user_avatar.js

// Good
userAvatar.js

Use PascalCase for classes.

// Bad
class userAvatar {}
class user_avatar {}

// Good
class UserAvatar {}

Use lowerCamelCase for variables and function.

// Bad
let dummy_variable = 'goof';

// Good
let dummyVariable = 'goof';

Use SCREAMING_SNAKE_CASE for constants.

// Bad
const dummy_variable = 'goof';

// Good
const DUMMY_VARIABLE = 'goof';

Use lowerCamelCase for key names in a constant.

// Bad
const DUMMY_OBJECT_VARIABLE = {
  PRIMARY_BUTTON: 'blue',
  SECONDARY_BUTTON: 'white'
}

// Good
const DUMMY_OBJECT_VARIABLE = {
  primaryButton: 'blue',
  secondaryButton: 'white'
}

Avoid var to declare variables, instead prefer using let or const.

// Bad
var dummy_variable

// Good
let dummy_variable

Use _singleLeadingUnderscore for private variables and functions.

// Bad
class Animal {
  // private methods
  privateMethod() {}
}

// Good
class Animal {
  // private methods
  _privateMethod() {}
}

Define event handlers methods as “public” methods (thus without a prefix _):

// Bad
class Dropdown {
  _onToggleClick(event) {
  }
}

// Good
class Dropdown {
  onToggleClick(event) {
  }
}

Methods must be placed in the following order: static, public then private

class Notification {
  static render(type, message) {
    // ...
  }

  constructor(elementRef) {
    // ...
  }

  // Public 

  onCloseNotification() {
    // ...
  }

  // Private

  _privateMethod() {
    // ...
  }
}

Use the following pattern to name event handlers: on + element/node + event type. The element/node can be omitted if it’s redundant.

// Bad
clickHandler = (event) => {}
buttonClick = (event) => {}

// Good
onButtonClick = (event) => {}
onTouchStart = (event) => {} 

When defining and binding custom events, the same pattern applies:

// Given this component and event listener to a custom event
const locationFilter = document.querySelector('.location-search__input');
locationFilter.addEventListener(LOCATION_SEARCH_SELECT_LOCATION_SUCCESS, this.onSelectLocationSuccess);

// The event handler will be the following:
onSelectLocationSuccess = () => { }
onLocationSeacchSelectLocationSuccess = () => { }

When it comes to unit testing, event handlers are key methods that requires to be tested, hence the need to make them public.

Project Structure

JS-only Applications

This structure applies to JS-only / Node.JS applications. Our architecture is inspired both by the accepted standards in the JS community but also by the Ruby on Rails framework 💪 .

app/
├── assets/
├── helpers/
├── initializers/
├── components/
├── screens/
├── index.js
bin/
├── build.js
├── setup.js
config/
├── locales/
├── index.js
dist/
├── ...
lib/
├── middlewares/
server/
├── index.js
spec/
├── support/
.eslintrc.json
package.json

app/: Close to 100% of the application code must be in there. It’s often named src/ but it must also contain non-JS files such as assets/ (which are often stored in public).
bin/: CLI scripts e.g. application setup, distribution build or deployment.
config/: The configuration files for the application such as environment variables and locales.
dist/: The compiled application code and assets for production deployment. Do not commit this directory to the GIT repository.
lib/: Non-specific application or shared code.
server/: The Node.JS web server configuration and boot scripts.
spec/: The tests for the application and the config for the test environment (stored in support/).
./: The root of the styles folder contains the NPM package configuration and other dot files.

If a library or framework e.g. Ember.JS has its own directory structure then use the one provided by the library or framework.

Front-end JS

This structure applies to applications in which JS is used solely on the front-end i.e. in a Ruby on Rails application.

├── assets
│   ├── fonts
│   │   ├── ...
│   ├── images
│   │   ├── ...
│   ├── javascript
│   │   ├── adapters
│   │   ├── components
│   │   ├── config
│   │   ├── helpers
│   │   ├── initializers
│   │   ├── lib
│   │   ├── polyfills
│   │   ├── screens
│   ├── stylesheets
│   │   ├── ...

All JS files must be stored into a single sub-directory named javascript:

adapters/: Code in charge of making network and/or async tasks. We usually create one file per API resource.
components/: Re-usable and stateless user interface components.
config/: The configuration files for the application such as environment variables.
helpers/: Any utilities used in the project. We usually create one file per utility of group of utilities.
initializers/: Code that initializes components used application-wide instead of having to bind each component on each page. We usually create one file per component initialized.
lib/: Non-specific application or shared code.
polyfills/: Provides browser specific enhancement. Usually, this covers code bridging the gap to a feature not yet available in all browsers and extensions of built-in functionality.
screens/: Page specific components which are in charge of coordinating the re-usable components and/or adding functionality that does not fit into a component. These components are also considered as root elements/containers when it comes to event handling.

Adapters

Avoid performing remote network calls inside components or screens. Instead, decompose this functionality into adapters classes:

// In a file named payment.js
import config from 'config';
import BaseAdapter from './base';

class PaymentAdapter extends BaseAdapter {
  /**
   * Create a new payment
   *
   * @param {Object} [payment] - payment attributes
   * @return {Promise} - a promise which will resolve to the payment completion response
   */
  static create(payment) {
    let requestParams = {
      payment: {
        provider_token: payment.providerToken,
        card_id: payment.cardId
      }
    };

    return this.prototype.postRequest(`${config['api']['payment']}`, requestParams);
  }
}

export default PaymentAdapter;

Then use this adapter into components or screens:

PaymentAdapter.create({providerToken: 'XghYhKJUnkd', cardId: 'etst-xyuhd'})

Prefer creating a base adapter class then extend it for each adapter.
In the base adapter, setup the generic request configuration (e.g. authorization token, content-type) which will be used by all adapters:

import requestManager from '../lib/requestManager';

const SELECTOR = {
  csrfToken: 'meta[name="csrf-token"]'
};

class BaseAdapter {
/**
   * Generates request headers for authenticated routes.
   * Appends the csrf token in the header, required by protected Rails routes.
   *
   * @return {Object} A request headers.
   */
  static requestHeaders(multipart = false) {
    const csrfToken = document.querySelector(SELECTOR.csrfToken);
    const token = csrfToken.getAttribute('content');
    const headers = {
      'X-CSRF-Token': token,
      'Accept': 'application/json'
    };

    return ({ headers });
  }

  /**
   * Make a GET request.
   *
   * @param {string} endpoint - the API endpoint to use.
   * @param {Object} params - params to be sent.
   * @return {Promise} A Promise that will resolve into an object or reject
   *                   with an error object for its reason.
   */
  getRequest(endpoint, params) {
    return requestManager('GET', endpoint, params);
  }
}

Components

Use a folder structure with an index file (and other files when required):

// Bad
components/
├── Button.js

// Good
components/
├── Button/
│   ├── index.js

This is both a future-proof measure and a mean to break down components into small meaningful modules:

components/
├── Button/
│   ├── index.js
│   ├── icon.js

All files that related to the component (e.g. template files, configuration) must be located in the same directory:

components/
├── QuestionList/
│   ├── templates
│   │   ├── answer.hbs
│   │   ├── question.hbs
│   ├── config.js
│   ├── index.js

Usually, the contructor method contains 3 private methods _bind, _setup and _addEventListeners:
- _bind: bind all functions to the local instance scope. Mostly used for binding event handler methods.
- _setup: bootstrap component actions such as elements initialization.
- _addEventListeners: group addEventListener of component’s elements together.

const CLASS_NAME = {
  closed: 'notification--closed'
}

class Notification {
  constructor(elementRef) {
    this.notification = elementRef;
    this.dismissButton = document.querySelector('.notification__dismiss-button');
    
    this._bind();
    this._setup();
    this._addEventListeners();
  }

  // Event Handlers

  onCloseNotification() {
    this.notification.classList.add(CLASS_NAME['closed']);
  }

  // Private

  _bind() {
    this.onCloseNotification = this.onCloseNotification.bind(this);
  }

  _setup() {
    this._setTitleText();
  }

  _addEventListeners() {
    this.dismissButton.addEventListener('click', this.onCloseNotification);
  }

  _setTitleText() {
    // ...
  }
}

It’s NOT compulsory for every component to have all these methods. Only define them if needed.

Initializers

Each initializer must import a component and a selector to bind the component to:

import Dropdown  from '../components/dropdown';

document.querySelectorAll('[data-toggle="dropdown"]').forEach(dropdown => {
  new Dropdown(dropdown);
});

Each initializer is then imported by an index file which will be imported from the manifest file application.js:

├── initializers
│   ├── calendar.js
│   ├── dropdown.js
│   ├── index.js
│   ├── modal.js
│   ├── notification.js

initializers/index.js has the following content:

import './calendar';
import './dropdown';
import './modal';
import './notification';

Screens

Use a file or folder structure with an index file (and other files when required):

// Single file
screens/
├── Home.js

screens/
├── Home/
│   ├── index.js

Each screen must import its required components and any needed default selector:

import SelectInput from '../components/selectInput/';
import BookingForm, { DEFAULT_SELECTOR as BOOKING_FORM_SELECTOR } from '../components/bookingForm/';

Define selector for screen and element reference which component is binded to:

const SELECTOR = {
  screen: '.home.index',
  categorySelect: '.category-select'
}

Example of HomeScreen that contain following components:

BookingForm which using DEFAULT_SELECTOR from its component.
CategorySelect which using SelectInput component so we need to define selector in this screen.

import SelectInput from '../components/selectInput/';
import BookingForm, { DEFAULT_SELECTOR as BOOKING_FORM_SELECTOR } from '../components/bookingForm/';

const SELECTOR = {
  screen: '.home.index',
  categorySelect: '.category-select'
}

class HomeScreen {
    constructor() {
        this.bookingButton = document.querySelector(BOOKING_FORM_SELECTOR.bookingButton);

        // Bind Function
        this._clickBookButtonHandler = this._clickBookButtonHandler.bind(this);

        this._setup();
        this._addEventListeners();
    }

    // Private Methods

    /**
     * Setup components
     */
    _setup() {
      new BookingForm();

      new SelectInput(document.querySelector(SELECTOR.categorySelect));
    }

    /**
     * Bind event listeners
     */
    _addEventListeners() {
      // ...
    }
}

// Setup the HomeScreen only on the home page
let isHomePage = document.querySelector(SELECTOR.screen) != null;

if (isHomePage) {
  new HomeScreen();
}

Each screen is then imported by an index file which will be imported from the manifest file application.js:

├── screens
│   ├── Checkout.js
│   │   ├── index.js
│   ├── Home/
│   │   ├── index.js
│   ├── index.js

screens/index.js has the following content:

import './Checkout';
import './Home';

Bundle/manifest files

Following this architecture, the manifest files only contain initializers and screens (in this respective order):

import './initializers';
import './screens';

Documentation

We follow JSDoc convention to document each function:

/**
 * Validate the Facebook account url.
 *
 * @param {string} url - the Facebook account url.
 * @return {boolean} Return true if the url is valid, otherwise, return false.
 */
_validateFacebookUrl(url) {
  const urlPattern = /http(s)?:\/\/(www\.)?(facebook|fb)\.com\/[A-z0-9_\-.]+\/?/i;

  return urlPattern.test(url);
}

We add a short description of the function followed by a list of parameters.