A good interface
is easy to use right
and hard to use wrong.
Most APIs get the first half.
Few get the second.
If a function takes
three booleans in a row,
someone will swap two of them
and it will compile.
If an object can exist
in a half-built state,
someone will use it there.
The fix isn't a comment.
It isn't documentation.
It's a shape that refuses the mistake.
Make the illegal state
impossible to construct.
Take a type, not a string.
Return the thing you promised,
not null and a note in the docs.
Every misuse you allow
is a bug someone else
will find at 2 a.m.
The best interface
lets the caller fall
into the pit of success.
They do the obvious thing
and the obvious thing is correct.
Design for the tired reader
reaching for your code
without reading the manual.
– Serguey Asael Shinder
