Formatters

The naive idea of a formatter is a text transformer: find things that look wrong and fix them with regular expressions. That approach dies immediately, because "looks wrong" needs structure — is this brace opening a block or appearing inside a string literal? — and because the number of cases is unbounded. Every real formatter does the same thing instead: parse, discard the layout, and print the tree. The output is generated, so it is uniform by construction rather than by exhaustive rule coverage.

The classic engine is Wadler-style pretty printing, and it is worth knowing because it explains the output you see. The printer builds a document made of concatenations, nested indentation levels, and *groups*, where a group is a construct that either fits on one line or breaks all of its separators. Then it walks the document with a target width: at each group, if the whole group fits in the remaining columns, print it flat; otherwise break it. That single rule is why an argument list is either entirely on one line or entirely one-per-line, and never half and half — the behaviour people complain about is not a bug, it is the algorithm being consistent.

Consistency is the deliverable. A formatter is not trying to produce the prettiest layout for each construct; it is trying to produce *the same* layout for the same construct everywhere, so that a diff shows a change in meaning rather than a change in taste.

Here is the part that surprises people building one for the first time. An AST is designed to drop everything that does not affect meaning, and that is exactly the material a formatter must preserve. Comments do not affect meaning. Blank lines do not affect meaning. The AST throws both away — see [[parse-tree-vs-ast]] — and a formatter built on one produces beautifully formatted code with every comment deleted.

So a formatter needs a [[concrete-syntax-tree]]: every token, in order, with its surrounding trivia attached. And attaching it is where the genuine difficulty lives, because trivia ownership is ambiguous in a way structure is not. Given a comment on its own line before a function, does it belong to the function (move it when the function moves) or to whatever preceded it? Given a trailing // ok after a statement, it clearly belongs to that statement — but a comment between a closing brace and an else belongs to neither cleanly. Every formatter has a documented, arbitrary-looking rule for this, and every formatter has open issues about it.

Blank lines are the second half of the problem. They carry authorial grouping — these three statements go together — and no formatting rule can reconstruct that intent. The standard compromise, used by gofmt, Prettier, Black and rustfmt alike, is to *normalise rather than regenerate*: collapse runs of blank lines to at most one (or two at the top level), remove them at the start and end of blocks, and otherwise leave the author's choices alone. It is the one place a formatter deliberately preserves input rather than deriving output, and it is the right call.

Go shipped gofmt with essentially no configuration: no indent width, no brace style, no line-length setting. This looked dogmatic in 2009 and has since been copied by Black ("the uncompromising formatter", one option that matters), by elm-format, by zig fmt and — with a handful of options that its maintainers openly regret — by Prettier. It is worth being explicit about what the decision actually bought, because "reduce bikeshedding" undersells it.

It ended the argument permanently. Not by winning it but by making it unavailable. There is no configuration file to disagree about, so no project spends time on it and no engineer carries a preference between codebases. The cost is real and should be stated plainly: your preferred style loses, and if you dislike Go's brace placement you will dislike it forever.

It made every Go file look the same, which enabled tooling. This is the underrated half. Once formatting is canonical, a tool that *rewrites* code can emit the canonical form and produce a diff containing only its own change — no formatting noise. gofix, goimports, gorename and the whole codemod tradition in Go depend on this. In an ecosystem with per-project formatting, an automated rewrite either preserves the original layout exactly (much harder) or produces an unreviewable diff.

It made diffs semantic. A diff that never contains reformatting is a diff you can review for meaning. This compounds: blame stays accurate, merge conflicts drop, and a reviewer's attention goes to the change rather than to the whitespace around it.

The generalisable lesson is not "options are bad". It is that a formatter's value comes from being a *normal form*, and every configuration option multiplies the number of normal forms in the ecosystem. One option is defensible. Forty is a style engine, and a style engine does not deliver what a formatter is for.

Three, and each has a failure mode you will meet if it is missing.

Idempotence. format(format(x)) must equal format(x). If it does not, the tool has no fixed point, and a repository with a format-on-save hook and a format-check in CI will oscillate: two engineers save the same file and get different bytes. This is the first property to test and the easiest to break with an ad hoc line-breaking heuristic.

Semantic preservation. The output must parse to the same tree and behave identically. Most of the time this is trivially true because only whitespace changed — but not always, and the exceptions are language-specific. JavaScript's automatic semicolon insertion means a line break before a leading ( or [ can change the parse, which is why Prettier adds a defensive semicolon in some positions. Python's indentation is syntax, so the formatter is editing the program's structure directly. C macros end at the newline. In each case, the formatter must know the language rule; a generic layout engine cannot.

Total input handling. Real files contain syntax errors while you are typing them, and an editor formats on save. A formatter that refuses to emit anything on a parse error is correct and useless in an IDE; a formatter that emits its best effort on a broken tree can destroy code. Most resolve this by declining to format when the parse fails and reporting why — which is the right default, and the reason error-tolerant parsing matters here for the same reason it does in [[language-server]].

One more thing worth stating: the formatter is not a linter, and keeping them separate is what makes both useful. A formatter produces output and no diagnostics; a linter produces diagnostics and, sometimes, fixes. When formatting rules live in the linter they compete for the same output channel as real defect findings, and the real findings lose — see [[linters]].