@deprecated is a lie

API is serious business. If you don't need to build reusable libraries, your life is easy. Refactoring tools will help you grow your code for the future. If you build in-house libraries and have only a few well known clients, your clients will hate you, but you can still make changes. For reusable public libraries such as SWT, nothing can change. Ever.

To really understand this, I think you need to have been burned by it at least once. Fortunately for me, this happened early in my career, in a different language and on a different project. I learned my lesson.

You can tell when API failure occurs. A quick search for @deprecated is all it takes. Some people think nothing of leaving a trail of dead API behind them, @deprecating all the way. "We'll just deprecate that" they say, like it fixes everything.

What's wrong with this thinking? For one, API never goes away. It still needs to be tested, debugged and maintained. It takes up space in memory and on disk. But there is a deeper cost. Clients have invested their time and energy learning your API and now you tell them, "Throw that away and start again, it's better this time".

Here is my rule of thumb: If there is any way, I mean any way, to keep an API going, then I'll do it.

We've done a good job of API in SWT over the years and I'm proud of it. SWT is particularly hard because the underlying platforms are so different. One false step leads to disaster. In SWT terms, this is an API where a native implementation is impossible. If you search the source of SWT 3.2 for @deprecated, you'll find only 39 matches in the entire toolkit. Some of these are duplicates because the Javadoc is copied onto all the different platforms. The actual number is 19.

Someday, I'll talk about a few of the things we do to keep it this way.

Steve