Types are documentation that can't rot

I used to document my code in comments and wikis. Then I watched both rot — the code changed, the docs didn't, and the documentation became actively misleading. Types fixed what neither could: they can't disagree with the code, because they are the code.

What types do that comments can't

They update under force. Change a field's shape and every place that depends on it turns red until it's fixed. A comment just quietly lies.

They document at the point of use. Autocomplete in six months is the documentation, delivered exactly where the next reader needs it.

They encode decisions. A status: "building" | "active" | "maintaining" type doesn't just describe data — it announces the legal states of my product's world and forbids everything else. That's design, enforced.

Where comments still win

Types describe shape; comments explain intent. Why a limit exists, what a workaround protects against, why the obvious alternative was rejected — none of that fits in a type. I keep both, with a clean division: types for structure, comments for reasoning.

The compounding payoff

In a content-driven site like this one, types are the quality control: a blog post missing a field fails the build instead of failing readers. The compiler became the most diligent reviewer I've ever had — it never gets tired, and it never gets polite.