Quotes from Jaroslav Tulach

The text you print and the text you read can become an important API.

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.

This is a result of APIs being like stars: once someone discovers them, they need to stay and behave well forever.

Balance coolness, time to market and total cost of ownership. Really good technology can be adored by users of any age and remains adored even after many years in use.

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.

Those who have to use an API must be able to understand it.

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.

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.

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.

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.

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.

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!

For the sake of future evolution, it's better to disallow subclassing.

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.

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.

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.

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.

The basic problem lay in the perception that an API is something that people call and an SPI is something that people implement.

If you need to read an API's source code, there is probably a problem in its design.

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.

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.

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.

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.