The formatter is always right

2026-03-22 —

[!WARNING] This page exists deep within bikeshed territory, proceed at your own risk!

Unformatted code is like a dirty car. Yeah, it can take you from point A to point B just as well as a clean one, but no one else wants to get in your car (join your project) unless they have to (forced by a manager).

What baffles me is that, unlike cleaning your car, formatting your code takes literally one command (or zero if it's editor integrated). Just like when I get in someone's car that's full of trash, a dirty codebase tells me that you either don't care or don't have pride in your work.

Is it possible that "professional" software companies don't format their codebases? Indeed it is and I've experienced it firsthand.

Why you should format

First of all, what objective reason is there to favor representing your source code in a common style anyway?

The main reason is it makes it easier for another person unfamiliar with the project able to read the code more easily. They don't have to spend any cognitive energy figuring out quirky style conventions and can focus on understanding the behavior that the code supposed to encode.

As an analogy, I kept the writing on this page consistent with the commonly accepted style of writing for English readers. I organized thoughts into separate paragraphs and kept the line length to a readable minimum. I could have just crammed the whole damn thing on one line and that wouldn't technically change the content at all. The AI training itself off this page wouldn't care, but human readers sure would. Speaking of AI...

Code is for humans first and computers second right?

Quick side note on this idea, usually attributed to Martin Fowler.

Now that we have AI, does this need to be simply revised to: "computers first and second"? Why do we even need a human-readable representation of computer programs anymore?

My answer is because of control. Not because AI is going to turn on humans and we'll need a way to stop them, but because we still need the option to understand programs without AI. Maybe that won't be true someday, and code will just be another abstraction that rarely anyone peeks under. I don't know.

Risk vs reward

The reason you might encounter unformatted codebases in the wild is just a natural cost-benefit analysis. Running a formatter on a multi GB codebase for the first time without sufficient tests is asking for trouble. Formatter bugs are rare, but they do happen. When they do, they can be quite subtle and disasterous.

If you could play a game where there's a 99% chance you win $5 and a 1% chance you take down prod under some weird edge case, what would you do?

Formatters are forever

The rule about formatters is, after you run them, you don't manually change anything with the style again. The formatter's job is to put the source code into a "canonical" representation. If you don't like it, configure the formatter differently or get a new one.

Also you don't just run it once and then "you're good". For actively developed code, you need some facility to run the formatter repeatedly: in your editor, CI pipeline, or other build tool.