Use Prettier

@stephanwlee and I want to run Prettier on TensorBoard.

Prettier is a code formatter for JavaScript, TypeScript, HTML, and CSS (among others). Its approach is different than that of most formatting linters, like ESLint: instead of identifying “bad patterns” and suggesting peephole fixes, it simply parses the entire file into a concrete syntax tree and re-emits the tree with a pretty-printing algorithm. This “uncompromising” nature makes it a pleasure to work with: it’s pretty much entirely insensitive to however the input was already formatted, and will give you entirely predictable results.

(It’s like Go’s gofmt, or Python’s black.)

Anecdotally, I noticed that my process of writing code changed fairly significantly when using Prettier. I can write hideous-looking one-line monsters, then simply save the file and have it automatically formatted correctly. (And if it doesn’t reformat on save then I know that I have a syntax error!) Unlike with ESLint and friends, I can actually completely forget about the formatting.

Why?

Most importantly, you don’t have to think about formatting while writing, reviewing, or reading code.

Consistent style also makes diffs smaller, and improves greppability (e.g., you don’t have to account for two quote forms).

Considerations

Style

Prettier’s code style uses a bit more whitespace than our existing code style. Running Prettier on our codebase increases the total LOC in JS, TS, HTML, and CSS files by 18%.

Prettier also indents TypeScript namespaces, while we historically have not, so this adds ~1 level of indentation to all TypeScript files.

This is all totally fine, imho; just wanted to mention it.

One-shot versus per-file incremental

The diff is fairly large:

$ git ls-files -z '*.js' '*.ts' '*.html' '*.css' | xargs -0 wc -l | tail -n 1
  87771 total
$ prettier --write 'tensorboard/**/*.'{js,ts,html,css} >/dev/null 2>/dev/null
$ git ls-files -z '*.js' '*.ts' '*.html' '*.css' | xargs -0 wc -l | tail -n 1
 103474 total
$ git diff --shortstat
 367 files changed, 70988 insertions(+), 55286 deletions(-)

Essentially every file is modified, as should be expected. Some tools will choke when trying to show a diff for a commit this large (e.g., vim-fugitive). There’s a valid argument that we shouldn’t design around those broken tools. But Prettier also supports an incremental per-file option:

  --require-pragma         Require either '@prettier' or '@format' to be present in the file's first docblock comment
                           in order for it to be formatted.
                           Defaults to false.

This would enable us to reformat fewer files at a time, while still protecting against backsliding. We could adopt a soft policy that we reformat files before modifying them, for instance.

Which should we choose?

Steps

Here’s what we need to do to make this happen.

• Make sure that all code is syntactically valid, so that Prettier can parse it. Done in #2423.
• Check in a .prettierconfig. (We like this one.)
• Either:
  • Add prettier -l 'tensorboard/**/*.'{js,ts,html,css} to CI, and reformat all code.
• Or:
  • Add prettier --require-pragma -l 'tensorboard/**/*.'{js,ts,html,css} to CI.
  • Adopt a policy of adding @format to all new files.
  • Adopt a soft policy of generally formatting files, modules, or packages (choose one?) before working on them.
• Update CONTRIBUTING.md to show how to configure format-on-save.

[wchargin]

For the same reason explained in the Why section, did we consider using Black?

Good question. I did consider it.

Black is even more uncompromising than Prettier. It is entirely unconfigurable except for max line length, and in particular it always uses 4-space indentation. This is standard in the Python community (cf. PEP 8), but not at Google—so much so that TensorFlow switched their style guide entirely from Google style to “PEP 8 but with 2-space indentation” to avoid a massive diff.

By contrast, Prettier’s default shiftwidth is 2 spaces, and this is also configurable.

Black will not support 2-space indentation. I’d assumed that this would be a dealbreaker (though I don’t personally mind either way, except for the obvious mega-diff, which I do care about).

There is a fork that uses 2-space indentation, so we could in principle use that.

[wchargin]

Merged!

For contributors:

• Run yarn fix-lint to reformat all files, which takes about 10 seconds on my machine. Run yarn lint to simply check formatting.

  (You will need to first install Yarn, and then run yarn once in the TensorBoard repository to install dependencies.)

• Consider enabling editor integration for format-on-save. I use the official vim-prettier plugin with configuration

  let g:prettier#autoformat = 0
  autocmd BufWritePre *.js,*.jsx,*.ts,*.tsx,*.css,*.html PrettierAsync
  

  which works quite nicely. It’s asynchronous, so it doesn’t make saving slow, either. The buffer generally updates about half a second after you save the file.