Rules that cannot be coded.

Use a verb and a noun to name a function

Reason

A verb gives clear indication of an intent to make an action. A function name that consists of a verb and a noun makes reading code a lot more like reading nature language.

Bad example

const precision = (value) => {
    return (String(value).split('.')[1] || '').length;
};

console.log(precision('1.123'));

Just by looking at the precision value, I cannot tell whether precision is a value or a function used to derive the value.

Good example

const getPrecision = (value) => {
    return (String(value).split('.')[1] || '').length;
};

console.log(getPrecision('1.123'));

It is always clear that getPrecision is a function used to get a value.

Order variable name components in a descending order of their scope

When variable name includes meta information (e.g. type of the variable, constructor name) order parts of the variable in a descending order of their scope, e.g.

Example 1

# Good
const fixtureOrderEvents = {};

# Bad
const orderEventsFixture = {};

fixture is the type of a variable. orderEvents is the contents of the value. Therefore the variable must be fixtureOrderEvents.

You can recognize this pattern in NPM project naming, e.g.:

• react
• react-redux
• react-redux-router

Example 2

# Good
type TypeResultSearch = Object;

# Bad
type ResultSearch = Object;
type TypeSearchResult = Object;
type SearchResult = Object;

It is tempting to leave out Type out of the name of the variable entirely. At the time of the variable type declaration, it seems superfluous. However, in the context of the code, variable ResultSearch does not provide enough information about the purpose of the variable (it could be a constructor).

Use full form of words to name variables

Reason

There are many ways a word can be abbreviated. Abbreviations save few characters at the cost of obscuring the scannability of the code.

Using words in their full form brings closer to reading a natural language.

Bad example

(err) => {};

Good example

(error) => {};

Use types to document parameters

Do not use JSDoc to document parameters.

Bad example

// Runs PhantomJS process to convert/download PDF invoices.
// query must contain:
// cookies - array of cookie objects
// urls - array of pairs { url, file }
export default (query) => {

Bad example

/**
 * Runs PhantomJS process to convert/download PDF invoices. Query must contain:
 * @param {Object[]} cookies
 * @param {Object[]} urls
 */
export default (query) => {

Good example

type TypeUrl = {
    url: string,
    file: string
};

type TypeQuery = {
    cookies: Array<Object>,
    urls: Array<TypeUrl>
};

/**
 * Runs PhantomJS process to convert/download PDF invoices.
 */
export default (query: TypeQuery) => {

When a type specific description is need, use @property tags, e.g.

/**
 * @property urls List of target sites.
 */
type TypeQuery = {
    cookies: Array<Object>,
    urls: Array<TypeUrl>
};

Use assertive form to describe test cases

BDD is not a collection of "should" or "must" assertions: BDD is a story. A test case describes a specific event that makes a story. Therefore:

# Good
it('converts number to a string', () => {});
it('removes accented characters', () => {});

# Bad
it('should convert number to a string', () => {});
it('should remove accented characters', () => {});
it('must convert number to a string', () => {});
it('must remove accented characters', () => {});