Comparison
AffordancevsPrinciple of least astonishment
Affordance
nobody used the option because nothing about the API suggested it was there.
What a thing's design suggests you can do with it. A door with a flat plate affords pushing; a function whose only parameter is a config object affords passing anything and hoping. In API and tooling arguments this is the word for why a technically complete interface still fails: the capability exists but the design does not offer it, so it is discovered by reading source code rather than by using the thing.
Full entry →Principle of least astonishment
the method called save() also sent an email, and somebody found that out in production.
A component should behave the way most people reading its name would expect. Astonishment is a real cost, paid by every future reader who assumes the ordinary thing and is wrong. It is the strongest argument against a clever design that is defensible on paper: being right is not enough if every user of it has to be told, because you will not be there to tell them.
Full entry →