Skip to content
Faysal HassaniFR

Type systems as documentation

The most valuable thing a type gives you is not safety at runtime but a claim the compiler will keep honest over time.

1 min read

Some opening argument for "type systems as documentation", stated plainly enough that the rest of the piece has something to push against.

The observation

The pattern shows up often enough that it is worth naming. It is easy to miss because each instance looks like a local decision rather than an example of anything general.

What follows from it

Once you accept the premise, a few consequences arrive whether or not you wanted them. Most of the interesting work is in deciding which of them to accept and which to design around.

Where it breaks down

Every rule of this kind has a domain. The failure mode is applying it outside the conditions that made it true, which is how good advice becomes bad practice.