search

researchstudio-sat / webofneeds

Finding people to cooperate with. Protocol, not platform. Decentralized. Linked Data. Open Source.
http://researchstudio-sat.github.io/webofneeds/
Apache License 2.0
63 stars 20 forks source link

Le big code-formatting day (aka spring-cleaning) #1642

Closed pheara closed 6 years ago

pheara commented 6 years ago

Issue: we have mixed tabs, 2-space, 4-space intendation, as well as a lot of other formatting and linting-issues.

Plan:

  1. the assignee prepares a branch, with an auto-formatter/-linter as part of the build and a pull-request hook, that assures that future (js- and java-?) code follows the style
  2. we pick a good day, where there's no long-open branches
  3. we merge everything
  4. we let the auto-styler run over the code-base
pheara commented 6 years ago

Which Code Formatter?

The three big ones seem to be:

Prettier

https://prettier.io/

https://www.npmjs.com/package/prettier

https://jlongster.com/A-Prettier-Formatter

a year old, now at 1.3M downloads (2018-05-15)

has a VSCode plugin

styles JavaScript, Flow, TypeScript, CSS, SCSS, Less, JSX, Vue, GraphQL, JSON, Markdown

due to it's age, some features are still under development (e.g. comment-formatting)

Style Alternatives

StandardJS

https://standardjs.com/

https://www.npmjs.com/package/standard

least widely used at 0.13M downloads

there's a VSCode plugin

styles javascript

AirBnB

https://github.com/airbnb/javascript

seems to be a bit more modular: there's eslint-config-airbnb, eslint-config-airbnb-base, airbnb-js-shims, babel-preset-airbnb, and quite a handful more on npm.

eslint-config-airbnb-base has 0.9M downloads, eslint-config-airbnb 0.7M.

there's no plugin for VSCode

styles javascript, jsx(?), css, ruby

Others

There's also the google-js-styleguide and idiomatic-js, but there's no editor-plugins or automatisation scripts that we could find with a reasonable web-search.

Decision

We'll use Prettier as it's got support for all languages we use, a plugin for the editor most of use, should have a straightforwared setup and seems to be the style that enjoys the widest usage of the researched ones.

Settings for Prettier

Prettier gives us a handful of options with rather sane defaults. However, we'd argue for activating trailing commas as it makes for better commits/git-blame. We might use 4 space intendation instead of the 2 that are the default.

Commit hooks

The prettier-documentation recommends using husky (docs) to automatically setup git-hooks when running npm install.

The documentation mentions 5 options for the hook:

  1. husky + lint-staged: "Useful for when you need to use other tools on top of Prettier (e.g. ESLint)".
  2. husky + pretty-quick: "Great for when you want an entire file formatting on your changed/staged files."
  3. pre-commit: "Great when working with multi-language projects." Downside: requires installing a tool using pip and thus a full python setup.
  4. husky + precise-commits: "Great for when you want an partial file formatting on your changed/staged files."
  5. bash script in .git/hooks/pre-commit: the fallback if nothing else works

As such, the first two (husky + linst-staged or husky + pretty-quick) are the most interesting options for us. The first is somewhat preferable, as we probably want to use linting in the future. There's a pre-commit.js (not to be confused with the python tool above) that we'll need for the npm task that installs the hook.

Issue: "Currently there is a limitation where if you stage specific lines this approach will stage the whole file after formatting." A slightly more complex task to fix this problem: https://github.com/okonet/lint-staged/issues/62#issuecomment-286830310. A somwewhat simpler solution: https://github.com/okonet/lint-staged/issues/62#issuecomment-381432450

Even simpler: switch to "no. 4: husky + precise-commits" as a solution.

On the other hand, we only need formatting for the entire file anyway.

Note, that when the husky major-version upgrade hits npm (and if we choose to follow), we'll need to slightly change our config, as described here: https://github.com/typicode/husky#upgrading-from-014

Useful Tips

If you want to already format on save, for vscode there's the "Prettier - Code Formatter" plugin. Additionally you want to add "editor.formatOnSave": true to your workspace settings (Ctrl+, then go to tab labelled "workspace settings"). There's also a build-hook that triggers when building and a commit-hook that makes sure everything is formatted and linted when committing.

pheara commented 6 years ago

Linting

ESLint is the standard, has integration with prettier and vscode. We used that in (almost) default settings and also included it in the pre-commit hook.