Stoicism JavaScript Style

ESLint and Prettier configurations for JavaScript in the Stoicism Compendium

This package combines the following configurations for linting and formatting JavaScript:

• An ESLint configuration based on the JavaScript Standard Style

• A Prettier configuration that works with the ESLint configuration

To determine the JavaScript code style in the Stoicism Compendium project, we started with the Standard Style, since it seemed to mostly match our goals (below). If we find useful​¹ changes, we add those to index.js, which has eslint and prettier components.

Our goals are to improve, in priority order:

1. the readability of code,
2. the readability of line-by-line code changes, and
3. the compactness of code.

The ESLint configuration extends the Standard configuration (eslint-config-standard), and we describe the differences relative to that. Under each item, there is a motivation and a comparison with the Standard ESLint rule.

It’s easier to read control flow code if the content between the braces is not on the same line as the braces themselves. This may increase the number of lines of code, but the trade-off of improved readability seems worth it.

| Style | brace-style | | -------- | ---------------------------------------------- | | Standard | ["error", "1tbs", {"allowSingleLine": true}] | | Stoicism | ["error", "1tbs"] |

Dangling commas are superfluous in single-line expressions, but they are helpful in multi-line expressions, where changes often affect only the last element. In the Standard Style, those changes add the extra noise of comma changes, which reduces the readability of diffs.

| Style | comma-dangle | | -------- | ------------------------------------------------------------------------------------------------------------------ | | Standard | ["error", {"arrays": "never", "objects": "never", "imports": "never", "exports": "never", "functions": "never"}] | | Stoicism | ["error", "always-multiline"] |

Braces are an important visual hint of control flow blocks, and consistent usage helps readability.

| Style | curly | | -------- | ------------------------- | | Standard | ["error", "multi-line"] | | Stoicism | ["error", "all"] |

Spaces inside object braces ({/}) increase line length while providing a minimal improvement to readability. Since array brackets ([/]) and parentheses ((/)) do not generally have spaces inside, it seems more useful to reduce the line length than to make a special case for braces.

| Style | object-curly-spacing | | -------- | ----------------------------------------------------- | | Standard | ["error", "always"] | | Stoicism | ["error", "never"] |

Spaces after a named function adds unnecessarily to the line length (with function names that may already be long). Also, by treating named functions differently, it is easier to quickly distinguish them from anonymous functions.

| Style | space-before-function-paren | | -------- | ------------------------------------------------------------------------------ | | Standard | ["error", "always"] | | Stoicism | ["error", {"anonymous": "always", "named": "never", "asyncArrow": "always"}] |

The Prettier configuration extends the default configuration, and we describe the differences relative to that. Under each item, there is a motivation and a comparison with the default Prettier option.

Spaces inside object braces ({/}) increase line length while providing a minimal improvement to readability. Since array brackets ([/]) and parentheses ((/)) do not have spaces inside, it seems more useful to reduce the line length than to make a special case for braces.

| Style | bracketSpacing | | -------- | -------------------------------------------- | | Prettier | true | | Stoicism | false |

This follows the Standard Style.

| Style | semi | | -------- | ----------------------------- | | Prettier | true | | Stoicism | false |

This follows the Standard Style.

| Style | singleQuote | | -------- | -------------------------------- | | Prettier | false | | Stoicism | true |

Trailing commas are helpful in multi-line expressions, where changes often affect only the last element.

| Style | trailingComma | | -------- | ------------------------------------------- | | Prettier | "es5" | | Stoicism | "all" |

Prerequisites

In the following sections, we describe how to install stoicism-js-style with npm and use it with eslint and prettier.

Alternatives include yarn instead of npm.

Installation

Install stoicism-js-style and its peer dependencies as a developer dependency:

npm install --save-dev \
  stoicism-js-style \
  eslint-plugin-standard \
  eslint-plugin-promise \
  eslint-plugin-import \
  eslint-plugin-node \
  eslint \
  prettier

Usage

Configuration

Create a file called .eslintrc.js:

module.exports = require('stoicism-js-style').eslint

Create a file called .prettierrc.js:

module.exports = require('stoicism-js-style').prettier

Script

Define scripts to run eslint and prettier on your JavaScript:

"scripts": {
  "check-js": "prettier --check '**/*.js' && eslint .",
  "format-js": "prettier --write '**/*.js' && eslint --fix ."
}

Run the scripts with npm run:

npm run check-js
npm run format-js

License

Blue Oak Model License 1.0.0 © Sean Leather

Footnotes

¹ Of course, our choices are subjective, but we feel they are well-motivated. ⏎