11.1. EdX JavaScript Style Guide¶

11.1.1. JavaScript Version¶

edX JavaScript should be written consistent with the latest ECMA-262 specification in order to ensure future support, the largest community and the availability of modern features. To support this syntax in older browsers, use Babel. Babel may also be configured to add syntax extensions widely adopted by the community of our recommended framework (e.g., JSX).

Note: Much of edX’s existing front end code is written conformant to the version of ECMA-262 released in 2009 (ES5). Files written in ES5 should be gradually converted to the newer standard as new development in those feature areas requires.

11.1.2. Code Style¶

In order to standardize and enforce Open edX’s JavaScript coding style across multiple codebases, edX has published an ESLint configuration that provides an enforceable specification. EdX JavaScript style generally follows the Airbnb JavaScript Style Guide, with a few custom rules. The edX ESLint Config is made available as an npm package that can be installed into any Open edX package.

Note: The edX ESLint Config for ES5 may be used where ES5 is in use. Both configs may be used in the same codebase through the use of ESLint glob configurations.

11.1.3. Testing¶

All JavaScript code should be tested using Jasmine. In addition, there are a number of Jasmine-based helper classes provided by the edX UI Toolkit.

JavaScript tests are run with Karma, along with karma-coverage to provide code coverage reporting.

For more information about testing JavaScript, see the description of testing for the edx-platform repository.

11.1.4. Documentation¶

All JavaScript code should be documented using JSDoc. For detailed information about using JSDoc, see the JSDOC site.

As a tool, JSDoc takes JavaScript code with special /** */ comments and produces HTML documentation for it. An example follows.

/** @namespace */
var util = {
    /**
     * Repeat <tt>str</tt> several times.
     *
     * @param {string} str The string to repeat.
     * @param {number} [times=1] How many times to repeat the string.
     * @returns {string}
     */
    repeat: function(str, times) {
        if (times === undefined || times < 1) {
            times = 1;
        }
        return new Array(times+1).join(str);
    }
};