Formatter

Code runs the same no matter how it looks. Two spaces of indentation or four, single quotes or double, the result is identical. So every developer settles into personal habits, and a single repository ends up holding files that look nothing alike.

The differences turn into work as soon as several people touch the same file. Early at Pagedeck, Theo edited someone else's file and his editor silently reindented the whole thing. He had changed three lines; the pull request — the request to merge a change and have it reviewed — showed 400 lines changed. His reviewer spent the session hunting for which of those 400 lines were real, and in the end Theo reverted the cosmetic ones and opened the request again.

Arguments came with it. Code review, the step where a colleague looks over a change before it merges, filled up with comments about indentation width, and when one side gave in the same discussion started over in the next file.

A formatter moves the problem out of the realm of taste and into a tool. The tool holds exactly one correct appearance, and whatever anyone types gets rewritten into it on save. The premise is that nobody argues about which style is better — the team accepts what the tool produces.

Three specific things go away.

1. Style arguments. Indentation width, maximum line length, quote style, whether a trailing comma follows the last item. The team decides the configuration once and never revisits the topic. That's a single 30-minute meeting, after which the weekly stream of review comments on the subject stops.
2. Noise in the diff. The screen that compares versions of a file shows only the lines that really changed — the 400-line example above shrinks back to three. This matters beyond review speed: it also decides whether you can later trace when and why a particular line changed through the Git history, Git being the tool that tracks changes over time.
3. Ramp-up time for new hires. Nobody has to read and memorize a style document. Saving the file produces the right shape, so there's never a first week spent collecting style comments.

What a formatter won't do is just as clear. A variable whose name doesn't match what it holds, a function that runs 400 lines, the same calculation copied into four files — those are structural problems, not appearance, and it leaves them alone. Adding a formatter doesn't make code better. It stops appearance from blocking the view when you try to judge whether the code is any good.

That limit is also why it is cheap to adopt. Because the rewrite never changes what the program does, a team can turn one on in an afternoon without planning a test window, which is rarely true of anything else filed under code quality.

Three approaches chase the same goal without a formatter. All three are still in use, and all three lose to a formatter at the specific job of making code look the same.

1. A written style guide. The team documents its rules and everyone follows them by hand. Reading it takes half an hour; following it takes attention every day. It's the first thing to collapse under a rushed fix, and checking whether it collapsed takes a human reader again.
2. Shared editor settings. Basic items like indentation live in a config file in the repository and each editor reads it. Almost no effort, but it covers very little. It'll stop tabs and spaces from mixing; it can't decide whether a function call with five arguments stays on one line or spreads across five.
3. Comments in review. A person notices and asks for a change. This is the slowest path and the one most likely to bruise feelings — the reviewer repeats the same remark forever, and the author feels held up over trivia. It also scales backwards: the more people join the team, the more of these exchanges happen per week, while a formatter costs the same at any team size.

In practice teams install a formatter and then add two layers around it. One layer runs it automatically on save in the editor. The other checks the formatting once more before anything merges, and that check belongs to continuous integration — the practice of merging changes often and running automated checks on each one. It's what stops code from someone who never ran the formatter from getting in.

"Run the formatter and push again. The check is failing."

Nothing is wrong with the logic; the shape doesn't match and the automated check blocked it.

"This file predates the formatter, so the diff looks messy."

The large number of changed lines is reformatting, not actual edits.

"Let's just take the formatter's default for quotes. It isn't worth debating."

A suggestion not to burn time tuning the configuration to team preference.

Pagedeck puts a formatter config into every new repository before anything else. Theo commits the configuration and the check script first, and from then on every piece of code lands in the same shape regardless of who typed it.

Retrofitting one onto an old, running repository takes a specific order. Run the formatter across everything in a single commit that contains nothing else, then mark that commit so history-tracing tools skip it. Skip that step and the last person to touch every line in the repository becomes Theo, which makes it much harder to work out who wrote a line and why. Any branch already open at that moment is going to conflict with the reformatting commit too, so the usual approach is to merge or close outstanding work first and run the formatter on a quiet day.

The most common belief is that a formatter improves code quality. The output looks visibly tidier, so the impression is a fair one. But the tool only ever looks at whitespace and line breaks; it makes no judgment about whether anything is wrong. A 400-line function becomes a neatly aligned 400-line function. Believe quality went up and you might defer the checks that actually find problems, leaving a repository that is evenly shaped and entirely unexamined.

The other one is assuming the configuration has to be tuned carefully to team taste. It's a tool, so adjusting it feels right — but the value here isn't a precise configuration, it's the disappearance of the argument. Start reviewing the options one by one and the taste debate you meant to kill simply relocates into a review of the config file. That's why many teams run the defaults untouched, and why newer tools deliberately expose very few options.