Designing APIs. One of the most important and most challenging steps in building modern software is designing APIs. Ideally, an API would clearly articulate behavior for all possible inputs, including side effects, and then we would have software to check that implementations meet the specification. Unfortunately, a fundamental result from theoretical computer science known as the specification problem implies that this goal is actually impossible to achieve. There are numerous potential pitfalls when designing an API:Too hard to implement, making it difficult or impossible to develop.Too hard to use, leading to complicated client code.Too narrow, omitting methods that clients need.Too wide, including a large number of methods not needed by any client.Too general, providing no useful abstractions.Too specific, providing an abstraction so diffuse as to be useless.Too dependent on a particular representation, therefore not freeing client code from the details of the representation.In summary, provide to clients the methods they need and no others.

Sources:

https://medium.com/@mbostock/what-makes-software-good-943557f8a488

http://algs4.cs.princeton.edu/12oop/

http://www.thereformedprogrammer.net/what-makes-a-good-software-library/

https://dannorth.net/2010/08/30/introducing-deliberate-discovery/