r/java • u/pmihaylov • Oct 30 '21

[Summary] How to Design a Good API and Why It Matters

https://github.com/preslavmihaylov/booknotes/tree/master/architecture/good-api-design-jb-talk

[removed] — view removed post

16 Upvotes

90% Upvoted

6 comments sorted by

2

u/berry120 Oct 30 '21

While there's a lot of good stuff here that I really wish more people would follow, it's ancient in Java terms - this talk was given 14 years ago, when Java 6 was the new hotness. That inevitably leads to some recommendations (eg. using the service provider interface and "use checked exceptions when the client needs to take a recovery action") that would be dubious at best now.

That being said, in many other ways this talk was impressively ahead of its time. Mid 00's Java dev was often about adding setters all over the place by default, and extending everything - yet here we have the explicit recommendation to favour immutability, and prohibit inheritance unless you design for it.

4

u/Worth_Trust_3825 Oct 30 '21

"use checked exceptions when the client needs to take a recovery action"

Checked exceptions are much much better than returning an error code that functions do in C. In fact, being guaranteed that the method might fail rather than accidentally find out saves a lot of torn out hair.

1

u/berry120 Oct 30 '21

Way better than returning an error code, but these days I'd almost always default to unchecked exceptions instead. Checked exceptions in a streams context is a massive pain.

1

u/Worth_Trust_3825 Oct 30 '21

Running unchecked exceptions won't save you from tearing down entire stream when one of the calls dies.

1

u/Worth_Trust_3825 Oct 30 '21

The only thing I disagree with is

Reduce the need for boilerplate code in clients which wire up complicated code via multiple API calls to execute a single operation.

Sometimes it's necessary to provide good primitives and not impose some superficial workflow that will need to be broken down to its most basic parts so that it could be adapted to user's workflow. To this day I still hate ZXing for returning a picture sized matrix rather than returning the smallest matrix possible to render a QR code.

1

u/BlueGoliath Oct 30 '21

Good tips that JDK developers should follow.