Should changing the documented performance of a method be considered a breaking change? [closed]

Question

It seems a common rule in software development is that once you have deployed a public API, especially if you've documented that API (which—yeah, you should have), you must think long and hard before making any changes that could break backwards compatibility with that API as such changes would be breaking changes. In fact I'm sure many developers would argue that you just flat-out should not do it at all, regardless of how long and hard you may think about it.

Occasionally a developer will actually document the performance of a method. A lot of MSDN docs do this, for example, using Big O notation. Would changing this also constitute a "breaking" change? Maybe that's not a clear question; put another way: should it be avoided?

It seems to me that in cases where, e.g., you might have developed a superior algorithm to solve a problem, if you had previously documented that this algorithm was O(N²) you might be forgiven for improving your API by replacing it with this superior algorithm which is, say, O(log N). Users of your API might notice this and would, I imagine, only feel glad for improvement.

On the other hand I wonder whether it would ever be considered "excusable" to worsen the performance of a component of your API for other reasons—e.g., you optimize for the most common use case which results in worse performance in the general case; you optimize for memory over CPU cycles or vice versa; you eliminate an external dependency that had caused other issues, etc.

My intuition tells me that improving performance is almost certainly always OK. What about the opposite? Is it OK, assuming you update your documentation? Is it just wrong? I'm just looking for some reasonable guidelines, here.

Answer 1

Well, if you make the performance better I doubt you'll get any complaints.

Otherwise, I'd say it depends. If you have access to the source code for all your clients, the upright thing to do would be to look through them all and verify that your change won't cause them any trouble.

If it is more complicated than that, and you are liable to make some use-case's performance significantly worse, then you should go talk to your clients and warn them of the change.

If you can't do that either (eg: a shrink-wrapped API of some kind), then yeah, it would probably be best to implement the change as an alternative call or something, and leave the old call alone.