Manifesto for Humane Software

The best code is the code we did not write. We prize what can be deleted without consequence over what is merely easy to change, and that over what must be rewritten when the world turns. New code arrives as a self-contained module with a narrow door.

We keep coupling visible. We name the connascence between our parts and prefer it weak and near. Naming is design; what we leave unwritten speaks as loudly as what we write.

We prefer the functional to the imperative. We reach for pure functions and referential transparency, and treat mutation as a deliberate exception, never the default, even in languages that invite otherwise.

We keep a functional core and an imperative shell. Effects, input and output, and edge cases live at the boundary, declared in the open. The center stays pure, and full of decisions.

We do not astonish. Behavior matches what a reasonable person already expects. Where we can, we go past "not surprising" and actively delight the people who read our code and use our work.

Our methods tell a story. They gather their inputs, do the work with confidence, deliver a result, and handle failure at the edges, read top to bottom, like prose.

Our comments explain why. Rationale, constraint, the gotcha, the deliberate ugliness, never a narration of what the code already says.

We hold our tests to the highest standard. We test, and we maintain those tests with care, because a flaky or dishonest test is worse than none. Correctness first, then speed; a test that passes for the wrong reason is a liability.

We ship no unspoken side effects. Before we change the system, we name who feels it downstream: other services, billing, data, CI, the person on call, and we surface the blast radius rather than hide it.