Code standards: JS

The status of this document is currently Work In Progress.

The following is our style guide for writing JavaScript. All JS contributions MUST adhere to this document unless there's a good reason not to; such reasons MUST have a linter ignore applied to them, and SHOULD be documented using a comment above the relevant code.

This guide uses RFC 2119 terminology.

1. Encoding

Use UTF8 encoding, without BOM. Ensure your editor is set to use UTF8 w/o BOM.

2. Language Version

Use features of ES6 or above where they are available. Prefer modern constructs over equivalents from previous language versions. Code will be transpiled to ES5 for builds, so we can use modern features without worrying about browser compatibility. Particularly:

• Use const, not var. Use let if your variable will be re-assigned.
• Use arrow functions, () => {}, where possible. Only use function if a this context is necessary.
• Use async/await, not callbacks or Promise. Only use a callback when calling an API that does not offer async.

3. Modules

Write code in ES6 modules. Group related functionality (such as code relating to posts routes) into a single file; split it into multiple files if the file becomes excessively long. Use import/export to reference code from other files.

4. Naming

Name all variables and methods using lowerCamelCase. SHOUTY_CASE may be used for constants (true constants only, not just all const variables).

Name files in snake_case, using a .js extension: mod_dashboard.js.

5. Spacing

• Indent code by four spaces. Do not use tab stops.
• Use a space either side of an operator, including assignments and declarations: 1 + 1, const foo = 'bar';, () => {}.
• Use a space between parameters in function declarations and calls: (foo, bar) => { }, sendFormData(form, 'POST').
• Use a space between key and value when declaring object literals, and between each pair: const data = {a: 1, b: 2};
• Do not write more than one statement per line.

6. Required optional elements

• Semicolons must not be omitted at the end of lines.
• Braces must not be omitted around block structures (including if/else blocks).

7. Line length

Do not write lines longer than 120 characters. Lines that would be longer than 120 characters must be hard-wrapped onto the next line, and every continuation line must be indented at least one more level than the first line. Wrapped lines may be indented further to align certain elements with one another.

codidact.createDangerConfirmationAudit(document.querySelectorAll('.modal.is-danger > .modal--body'),
                                       'POST', 'https://codidact.org/audits/danger-confirmation');

8. Bracing

Follow the K&R style of bracing:

• No line break before opening brace
• Line break after opening brace
• Line break before closing brace
• Line break after closing brace

A blank line must also be added after a closing brace where the brace closes a function, method, or class body.

class ModalDialog {
    constructor(data) {
        if (Object.keys(data).length > 0) {
            this.dataset = data;
        }
        else {
            this.dataset = {};
        }
    }

    get name() {
        return this.dataset['name'] || '(none)';
    }
}