stoicism-js-style

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.

This is the ESLint configuration.

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.

Use the one true brace style without exceptions.

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"]

Require dangling commas in multi-line expressions.

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"]

Require braces for all control flow.

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

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

Disallow spaces inside object braces.

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"]

Disallow spaces after named functions.

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"}]

This is the Prettier configuration.

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.

Don't use spaces inside object braces.

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

Don't use semicolons.

This follows the Standard Style.

Style	semi
Prettier	true
Stoicism	false

Use single quotes.

This follows the Standard Style.

Style	singleQuote
Prettier	false
Stoicism	true

Use trailing commas in multi-line expressions.

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. ⏎