API Designer

From APIDesign

Current revision

Why did I decide to be an API Designer with a strong emphasis on BackwardCompatibility?

I've been working on the NetBeans project since middle of nineties. One day, I guess in a year 1999, a product manager stopped by and started to shout at me:"We need partners, we need people to code plugins for NetBeans. We need compatibility. Are we compatible or not?" I started to explain we are compatible - just a few methods and classes were renamed, deleted, but nobody was supposed to use them anyway. The shouting however got even worse: "That is not compatible! We need full backward compatibility! Keep it!"

Up until that moment we treated BackwardCompatibility from a practical point of view. We were ready to sacrifice it when we had a vague feeling it does not matter to keep it. However that one moment changed everything.

Since then I decided to treat compatibility seriously and keep 100% BackwardCompatibility. As I studied computer science at mathematics and physics faculty, I decided to apply as mathematical approach as I was able to find ways to really keep absolute compatibility. No excuses, no cheating, just 100% BackwardCompatibility. I guess NetBeans platform API compatibility history is a good proof showing we gained some knowledge in this respect.

To transfer that knowledge to my colleagues I invented an APIFest game (described in Chapter 17 of TheAPIBook). Playing such game really seems to improve the 100% backward compatibility skills. It comes with a bit academic approach, in real world one is usually OK with "99%" compatibility, but by taking things to extreme, the APIFest nicely shows the point.

Don't be afraid to ask us to prepare an APIFest game for you! Find out why BackwardCompatibility matters!

User comment by Daniel Latrémolière: Compatibility is highly important, but not broking compatibility sometimes can be complex (code difficult to read or problem for finding an asked method; by example). When an API need to be broken, then a good solution is broking API while insuring good binary compatibility by using a small compatibility layer for implementing old API on new API(s).

If the compatibility layer (no big idea in its code then no need of copyright) is released under an AS IS licence like BSD, the API user can use its code for refactoring easier its own code from old API to new API (with help of IDE). By example a non-modular API can be refactored in a non-modularized compatibility layer (for old users) calling two modularity-aware API (for new/updated users).

My reply: Thanks for leaving your comment. Yes, keeping the old APIs around may complicate time to market as newcomers may have hard time to find the way to do things right. Sometimes one wants to send old API to a blackhole - actually the Chapter 19, End Of Life Procedures of TheAPIBook contains description how one can keep BackwardCompatibility and still get rid of the old, deprectated APIs.