How To Design A Good API and Why it Matters
Why Stack Overflow recommends it
Stack Overflow users link it when discussing API design choices, such as encapsulation, avoiding inheritance, and not surprising API users with unexpected defaults.
Recommended by 3 people across 3 different months, 2013 to 2024.
What it is
A 2007 Google Tech Talk in which Joshua Bloch, author of Effective Java and designer of the Java Collections API, explains how to recognize good and bad APIs and gives concrete guidelines for designing them. It is a one-hour lecture from Google's Advanced Topics in Programming series.
What people said
Strong rec Mick Mnemonic · 2015-03 · Stack Overflow · on “Extending Guava collections”
These classes were designed not to be extended . Because inheritance essentially breaks encapsulation, it makes the API cleaner when classes can't be extended. (Related thread here: Good reasons to prohibit inheritance in Java? [LINK] ) You can generally work around this by using composition instead. To answer your follow-up questions: Regarding Java Collections API, I think there are two alternatives: either classes like ArrayList or HashMap were designed to be extended or then this is simply an API design flaw. I suspect the latter; but it is impossible to revert this design choice after the API has been published. Perhaps only abstract classes such as AbstractList should have been declare
Recommends Pro-grammer · 2013-11 · Stack Overflow · on “Design pattern to structure game programming code”
Im programming a library, I want to structure my code in a way that potential users find it easy to use this library. I have looked at this [this video] excellent video of great API design. One of the golden rules is to have a good design pattern. I have two in mind. The Facade design patten and the factory design patten. Both these design pattens are used to achieve a great level of abstraction in program code for users to use. Im finding it ever so difficult on which or if both to apply. Of course, I would like to avoid having anti-pattens. The language I am using is Python, which is quite different to Java Which is emphasised in the video link provided above. How my library would work: Charact
Recommends Vince · 2014-09 · Stack Overflow · on “Some clarification with Java OOP theory?”
Josh Bloch gives a good example as to how encapsulation helps users modify APIs without breaking the code of whoever is using it ( [this video] ).
Cites jub0bs · 2017-02 · Stack Overflow · on “Is using Optional in Scala's case classes and classes fields a code smell?”
Short answer Option fields have use cases; they're not intrinsically bad. However, even though several well established libraries (e.g. ScalaTest [LINK] ) define classes with Option fields, the latter, IMO, tend to be a code smell, as they often try to do too much for their own good. In many cases, a type containing optional fields can easily and advantageously be replaced by an algebraic data type. An example The domain Consider a business domain dealing with accounts. An account starts its life one day as an open account, but may eventually be closed . Accounts, among other data, contains the dates on which they were open and closed, where applicable. Using an Option field Here is an imple
Critical hlovdal · 2024-02 · Stack Overflow · on “Polly handles a few exceptions like expected first but then System.Private.CoreLib.dll steps in and triggers an unhandled exception”
Thanks @HansPassant, adding `MaxRetryAttempts = int.MaxValue,` was indeed the missing issue. Could you add that as an answer that I can accept? To me such default is a hard fail on user of API should not be surprised by behaviour [this video] .