Code formatting

Shields uses Prettier for formatting and I’ve started using it on all my JavaScript projects. The experience is really delightful. You type, save, and then your syntactically correct valid JavaScript is transformed into pretty JavaScript.

A dev I worked with on Shields who works at Facebook once said he takes auto-formatting so much for granted that, when he sees an editor that doesn’t do this, he feels like something has broken. At the time this sounded so opinionated and a bit silly, though to my amazement I now feel the same way.

Even compared to eslint autofix, Prettier saves a massive amount of time. It’s like instant autofix for the issues which don’t matter.

This is the way I usually set it up:

1. Add to contributing guidelines something like:

This project formats its source code using Prettier. The most enjoyable way to use Prettier is to let is format code for you when you save. You can integrate it into your editor.

1. Set up a prettier script which reformats all the code for easy running from the command line.
2. Set up a prettier-check script which runs in CI.
3. Specify the patch version of prettier in package.json and use Dependabot to keep it up to date.
4. Use eslint-config-prettier to auto-disable the formatting-related eslint rules (i.e. the ones which conflict with prettier).

It blends familiar workflow (CLI) with modern workflow, and provides a better, less distracting mental model than routing prettier through eslint (see below about separation of responsibilities).

One of the design goals of standard was to end the pointless debates on style conventions which end up wasting a lot of time over things which don’t make a bug difference. Prettier took a similar approach: it’s similarly opinionated and barely configurable.

Separating the responsibilities of code formatting and linting also turns out to be a great idea. It means typically when you run the linter, you’re finding out about real problems, whereas the irrelevant formatting is instantly addressed without your intervention.

With prettier or not, I’ve found the standard CLI too restrictive as it doesn’t provide a way to add additional automatic checks, to turn off rules which don’t make sense for a given project, or to work around bugs. I like good defaults but judicious configuration seems better than sprinkling ignores throughout the code. So I use eslint-config-standard instead. In Shields we’ve add a good handful of rules, including prefer-const, prefer-template, promise/prefer-await-to-then, and strict. We also tweak sourceType. (It’s possible some of these adjustments aren’t necessary in latest versions of eslint-config-standard.)

These are the options I usually use: https://github.com/badges/shields/blob/master/.prettierrc.yml

The trailing commas and no semis are both timesavers for copying and pasting.

By default my editor integration will also format json, yaml, and markdown files, including JS code blocks within the markdown, so we’ll have to decide whether we want that. It’s easy to turn off, if not.

@gr2m in #868 you proposed using standard; so I’m curious your thoughts on this.

I realize I’m spending too much time manually formatting code as part of e.g. #1286 #1287 #1288 and think it makes sense to move forward with automatic formatting, one way or another!

[gr2m]

Right now all I want is to keep you happy so lets go with prettier 😃 Could you maybe add a section to CONTRIBUTING.md about how to setup the auto-formatting in the different browsers? No need to write it all down for the different editors, linking to other resources will suffice

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue and add a reference to this one if it’s related. Thank you!