Code Style - acolorbright/handbook GitHub Wiki

Rationale

Code style conventions help to standardise a codebase when it is being worked on by multiple people in a team. It saves time and mental overhead by increasing familiarity when switching projects.

Linters help with this by issuing warnings and errors when editing files, and often times can fix the issues for you. Combined with git hooks and/or test commands, we can even prevent non-passing commits from landing or the build from passing to maintain the integrity of the codebase.

External tools

We have developed a standard linting setup for Python/Django, JavaScript, and CSS/Sass. These linting rules may be overridden and adapted for each project as necessary, but please think very hard before doing so.

JavaScript

We use ESLint to lint our JavaScript projects. New projects should be configured to require as a dev dependency, which will result in an installation local to the project. See the JavaScript section below for more details on installing the required dependencies.

CSS / Sass

...

Python

We use Flake8, which is based on the PEP8 styleguide, to lint our Python projects. You should install Flake8 globally on your system.

We also use isort to maintain the sort order of imports. You should install both isort and its Flake8 integration flake8-isort globally too.

$ pip3 install flake8 isort flake8-isort

Internal tools

We have extracted our typical linting setups for both JavaScript and Python into their own packages, which should be installed into new projects.

JavaScript

For JavaScript projects, there are two different ESLint configurations available:

• For React projects: eslint-config-acb
• For non-React projects: eslint-config-acb-base

See the README of each project for instructions on installing peer dependencies.

CSS / Sass

...

Python

...

Code editor plugins

Many common code editors may be integrated with linters to make identifying and fixing linting issues during development faster and easier. We recommend installing the appropriate plugins for your editor of choice.

For linters which provide a fix option to fix simple errors automatically (such as ESLint), we recommend turning on the option to “fix errors on save”, if available in the plugin.

Atom

• EditorConfig
• linter
• linter-eslint
• linter-sass-lint
• linter-flake8
• python-isort
• sort-lines

Sublime Text

• EditorConfig
• SublimeLinter
• SublimeLinter-eslint
• SublimeLinter-flake8

to run eslint --fix on the current file (and with the correct node version), use ShellCommand with this custom command (save it in ~/Library/Application\ Support/Sublime\ Text\ 3/Installed\ Packages/ShellCommand.sublime):

{
    "caption": "eslint-fix",
    "command": "shell_command",
    "args": {
        "command": "export NVM_DIR=\"$HOME/.nvm\"; source /usr/local/opt/nvm/nvm.sh ; npx eslint --fix ${file}",
        "refresh": true,
        "wait_for_completion": true,
    }
}

Vim

• EditorConfig Vim Plugin
• ALE (Asynchronous Lint Engine)

In order to use Flake8 with Python3 code the following needs to be added to ~/.vimrc:

let g:ale_python_flake8_executable = 'python3'
let g:ale_python_flake8_options = '-m flake8'

VS Code

• EditorConfig
• ESLint
• Flake8 Linting

For ESLint plugin it is super handy to check Auto Fix on Save in Settings. Or in JSON notation: "eslint.autoFixOnSave": true