brutalist-software

Brutalist software optimizes code for a reader with bounded context: the coding agent and the human reviewing at 3 a.m. What you read should be what runs, with no action at a distance. Apply this lens to the code you are about to write, change, or review.

The rule

An abstraction must be self-evident at the point of use. Understanding it must cost no more than one local jump.

A local jump is a short hop to a small definition in the same neighborhood. Read it, return, done. The jump tax is what you pay when understanding one line means chasing behavior through many layers or leaving for remote docs you can't see. Brutalism keeps jumps cheap and local.

Choosing an abstraction, dependency, or pattern

For each one you reach for, in order:

1. Self-evident? Does the name and signature faithfully predict the behavior without opening the source? stripe.charges.create() does; a user.posts that silently fires an N+1 does not.
2. Will you need what it hides? A facade is honest only when there is nothing behind it you'll have to reach for. An ORM hides SQL you will need: the N+1, the missing index, the query plan. Brutal-reject. The Stripe SDK hides HTTP you'll never touch; keep it. What matters is whether you'll need what it hid.
3. One jump? Apply the rule above to this reach: a five-line function next door is fine; anything costing more than one cheap, local jump is not.

Done when every abstraction introduced or touched in the change passes all three, or is named as a deliberate exception with its reason.

Don't over-correct