Accurate by design
An API should say what it will do and do what it says.
You should not have to read the code behind the API to call it. There should not be a “tribal knowledge” on the behavior of the API.
It should not have unintended consequences not described in the API.
One litmus test to do is to ask if none of the engineers are in the team anymore whether they would be any context lost not conveyed by the API.
Mastering Software Engineering Course on Maven
If you liked this article, I will be teaching a “Mastering Software Engineering” course on Maven where I will teach hard-learned lessons I acquired developing large-scale products at companies such as Uber, Airbnb, and Microsoft.