Luboš's Reviews > Practical API Design: Confessions of a Java Framework Architect

Practical API Design by Jaroslav Tulach
Rate this book
Clear rating

by
16037775
's review

really liked it
bookshelves: software-development

Very useful. Using Java 5, so a revamp could be handy (Java 8 default methods, Java 9 modules), but the most stuff is still applicable. Moreover there is some newer tooling than Ant. Interesting philosophical digressions.
1 like · flag

Sign into Goodreads to see if any of your friends have read Practical API Design.
Sign In »

Quotes Luboš Liked

“My experience tells me that API users are really creative. Sometimes the API user’s horizon is farther than that of the API designer. If there is a way to misuse something, users are likely to do so.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“You don’t want to understand the design of a car to drive it. You don’t need to understand chemistry to clean teeth. In a similar way, you don’t need to understand Windows’ code to write a simple Win32 application. You can become pretty efficient in programming for Windows just by having a working knowledge of the APIs (in this case the Win32 API) and knowing where to find the appropriate documentation. This is true for almost all systems. To code for Linux, Java, and the Web, you can learn just a tip of an iceberg and that is enough to get most of the coding done. The reason for this is the abstraction that wraps around every library or framework. This abstraction—the API—hides all the complexities.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“The text you print and the text you read can become an important API.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“Beware of situations where there is no alternative to parsing text messages! If the information isn’t available in other ways, people will parse any textual output generated by your code.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“This is a result of APIs being like stars: once someone discovers them, they need to
stay and behave well forever.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“Those who have to use an API must be able to understand it.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“The most similar activity to writing an API is writing a book: one writer and a lot of readers. The readers know something of the writer, but the writer knows little or nothing about the readers. Guessing their skills and knowledge correctly is part of the delicate art of making an API that is easy to understand.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“Every API writer needs to have an evolution plan; that is, to know on a strategic level what will happen to the API in future releases.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“Giving up and writing another API to perform the same task avoids the problem of incompatibility. The old API can stay the same, so no potential problems occur for its clients, and the new API can offer new and better possibilities. The only problem here is that old clients will stick with the old API unless they rewrite their code and upgrade to a new version of the API.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“Adding new methods into classes that can be subclassed endangers source compatibility, but that’s not the only point I want to make here. Adding new classes into existing packages might also cause problems.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“Because you cannot speak to unknown clients, there are only two solutions: either find your users and do a usability study, or be use case oriented. Work with use cases—that is, visions of the API user’s action—and then optimize specifically for these. Getting responses from users via a usability study is good and can verify that your expectations about the use cases are correct.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“When a user of the API complains and requests the element to be visible, you can still make it visible. However, don’t do so sooner than requested and not without a convincing use case!”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“For the sake of future evolution, it’s better to disallow subclassing.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“One lesson we learned the hard way after years of NetBeans API development is, “Don’t put setter methods in the true API.” By “true API,” we mean the interfaces that must be implemented to provide something. If setter methods are needed at all—and usually they aren’t—they belong only in the convenience base classes.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“Of course, explaining object-oriented programming as an enhanced switch is much less fancy than presenting it as a technology that helps us model the real world.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“So it’s reasonable to ask, “Is there actually any reason to use abstract classes?”
The short answer is “No.” Abstract classes in an API are suspicious and often indicate an unwillingness to invest more time in the proper API design. The longer answer is, “Well, there might be reasons to use abstract classes in APIs after all.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“The path of evolution depends on the type of interface: additions to an API are acceptable, while removing functionality is not. In SPIs removals are allowed, while additions are not.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“The basic problem lay in the perception that an API is something that people call and an SPI is something that people implement.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“If you need to read an API’s source code, there is probably a problem in its design.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“This is just another example of API users engaging in “empiric programming.” They don’t care about what is right or wrong, but only what works and what doesn’t. Because this coding style simply used to work, API users exploited it without any problems.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“It was no help to show them their code and prove that it was incorrect to start with, or that it had violated the documentation all along. “It used to work; now it doesn’t. And it’s your fault!”We tried to fix the most visible misuses of the API ourselves. But we couldn’t find them all, because just like a star that doesn’t know who is observing it, we were unable to find all the places that incorrectly mixed java.io.File with FileObject. Instead, we provided a migration guide that explained how to map the old bad code patterns to new and better ones. It still wasn’t enough and the complaints were endless.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“According to Hansen, a real monitor should allow a compiler to verify that the code is correct and thus help to eliminate programming mistakes. However, Java simply uses something that looks like a monitor, but doesn’t provide any of a monitor’s benefits. The Java compiler knows almost nothing about synchronization.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“Even if complete immutability might not be possible, it’s beneficial for regular mutable objects to keep their internal state in immutable data structures, because that allows easier synchronization when the object is modified from multiple thrads or in a reentrant way.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect

“It’s always good to motivate migration by means of some kind of bonus. For example, offer functionality in the new API that cannot be achieved in the old version.”
Jaroslav Tulach, Practical API Design: Confessions of a Java Framework Architect


Reading Progress

June 24, 2019 – Started Reading
June 24, 2019 – Shelved
June 24, 2019 – Shelved as: software-development
August 9, 2019 – Finished Reading

No comments have been added yet.