Inside SWT

Monday, June 19, 2006

@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

10 Comments:

  • This joke is related.

    By Anonymous Anonymous, at 6:54 PM  

  • Wrong, wrong, wrong. Learn from Apple, dude :)

    By Anonymous Anonymous, at 6:01 AM  

  • Anon-y-mouse,

    Do you program and maintain a large code base? Continually rewriting code might be fine for small applications but it's not practical for large ones. The cost is too high.

    Steve

    By Blogger Steve, at 9:58 AM  

  • This comment has been removed by the author.

    By Blogger dante, at 4:29 PM  

  • Sorry, the previous one was incomplete.

    Really, I wasn't talking about continuous rewrite. I just mean, that if you mark something as @deprecated, you should delete it in the next two releases. And those who doesn't honor your decision should stick to old versions. After all, you cannot make everyone happy, can you? :) :)
    So, all I'm saying, that you should not afraid to break someone's build, because coding with deprecated methods is really bad practice.

    Thanks for reply,
    Dante

    By Blogger dante, at 4:32 PM  

  • Hi Dante!

    I understand and agree with the concept. If you provide an API and you can fix all the clients, then I can see it. However, I have never seen a deprectated method get deleted, so in practice, API is forever.

    The only chance you really have is moving to a completely new API(cocoa, WPF) or implementing a major new version and shipping both the new and old (ie. GTK 1.0 vs GTK 2.0) libraries.

    Steve

    By Blogger Steve_Northover, at 9:32 AM  

  • Hi Steve,
    I guess we're talking on the same topic in two threads simultaneously.
    Yes, the best chance is major version move. However, I think that if you announce that all deprecated methods will be deleted in a (month? year? or two? just an exact date that's not too soon and not too far, and that won't change significantly), don't you think people will consider this in their planning?

    By Blogger dante, at 6:30 PM  

  • Let's discuss it here (or drop it, agreeing to disagree).

    I have a final real world example for you. I wrote some java code a while back that projects slides while my band plays. It makes use of Windows API that dates back to 16-bit days. I could rewrite the code and fight with it or I could get on with jamming and playing in the band. Also, other people (non-programmers) have the program. Microsoft keeps the crappy API going and we're all happy. Microsoft breaks it or deletes it, and we're all (temporarily) screwed.

    One day I will rewrite the code or find a shareware program that does what I want but what I have no works (which is all I care about for now).

    Steve

    By Blogger Steve, at 10:06 AM  

  • Steve, I think that we represent two extremes, and the truth is actually somewhere in the middle :)

    By Blogger dante, at 7:59 AM  

  • Agree

    By Blogger Steve, at 10:12 AM  

Post a Comment

<< Home