Comment by btilly | Hacker News Reader

Comment by btilly | Hacker News Reader

The key problem here is that "backwards compatibility" means "backwards compatibility for people abusing the API in undocumented ways".

Don't do that. That way lays insanity. Be very, very clear up front that you will break backwards compatibility for those folks. Don't sweep it under the table, be very vocal about having done it. There will be short term pain as important customers (eg Adobe) learn the hard way that you really mean it. And long term relief as you don't have that legacy headache growing so quickly.

One estimate is that a 25% increase in requirements results in a 100% increase in software complexity. (See Facts and Fallacies of Software Engineering for a source.) That means that the complexity grows as the number of requirements cubed. Therefore the key to a good API is that it be short and simple. When you start to add implicit requirements on top of explicit ones, it quickly becomes long and complex, and the necessary software to support it and make future modifications becomes much worse.

This does not mean that designing APIs is not hard. But don't let your API become what is published and quirks that are not. Just don't.

Your API documentation (or specification if you have one) is not your specification. Your API implementation is your specification, especially if you are the only provider of the API. I realize how trite that sounds, but it's true. Defensive API design (make it REALLY HARD to have undocumented tricks that developers can use in productive ways) is dramatically harder than API design is in the first place, and I still guarantee you'll screw it up for any moderately expressive API.

It's not just an issue of parameter validation or well-defined calls; it's the interactions between calls where this is hard. It's issues of ordering, timing, when you can secretly skip synchronization because you know the API will synchronize just enough for you to get away without something more heavyweight, things like that. And then when you have paying customers? Yeah, you can't break their code, even if it's bad, because if you do you won't have customers for very long.

OP here.

I think this is very naive/utopian.

Yes, be super focused in your design.

Yes, only expose APIs you have clear use cases for.

Yes, keep the surface area as small as possible.

Yes, have very focused requirements.

Yes, document the hell out of things.

Yes, implement strong parameter validation and other things to try to reduce the chance people do bad things.

Do all these things and more (these are all part of what makes exposing APIs hard work, that many people don't do).

But do not, for one second, believe that someone still won't do it wrong or abuse your perfectly designed API eventually... especially if it is successful.

I agree with all of what you just said. But I think that the post is not a good demonstration of that.

Microsoft failed at keeping the surface area as small as possible. When their surface area expanded to a hack to deal with Adobe's hack of replacing code behind Microsoft's back, they went into very dangerous territory.

If an end-user upgrades their operating system, and Adobe WhateverIUse stops working, who do they blame?

Adobe.

That is a wish, not the truth. It is self-evident that if I upgrade my OS and an app stops working, it is the upgrade's fault. I'm sure there is a "law" of "whoever last changed something broke it."

So, it's the users fault then?

It's not as simple as that. If it's just Adobe WhateverIUse that breaks, sure, people will blame Adobe. But if it's Adobe WhateverIUse that breaks AND WordPerfect WhateverSomeoneElseUses and maybe also Borland SomethingSomeoneElseYetAgain uses word will get around that the new operating system "breaks things" and people will stay away from it.

Even if noone will ever use all three of the broken apps.

In this sense, maintaining backwards compatibility is simply a matter of reputation management.

> If it's just Adobe WhateverIUse that breaks, sure, people will blame Adobe.

Not a chance. People will blame Microsoft, because WhateverIUse worked perfectly before. The only parameter which changed is that they updated the OS, therefore the OS is to blame.

They will blame both initially. Pissed off people are pissed off, and distribute blame randomly. That is the short term pain. However if it broke AND Microsoft stated up front that it really was Adobe's fault, Microsoft would have taken less of the blame. Not none, but less.

The flip side if Microsoft had bitten that painful bullet up front, then I believe that going forward companies like Adobe would have learned to not try to hack the system like they had. That would have given everyone, including Microsoft, a better reputation.

But of course Microsoft did not do that. And now Microsoft has such a history of nasty bugs that, even if Microsoft is in the right, nobody is going to believe it. (Which of course locks Microsoft into its current strategy of bending over backwards to accommodate everyone else's bugs, causing more bugs...)

If they'd done that to the 6502 CPU and variants, every single non-trivial game or program would have broken.

Behind almost every successful API is a big ugly mess of backwards compatibility to keep customers happy.

Reply on news.ycombinator.com