Path to remove deprecated APIs

We have some external APIs in our codebase that have been deprecated over the years, with no clear path on who/when to remove them. How would you recommend we would go about removing them? Can we consider APIs that have been deprecated for example >2 years or 3 releases back old enough just to remove them? Or should we first clearly communicate a removal strategy for each individual API and start removing them a couple of releases forward?

Any insights? How have you handl开发者_StackOverflowed this?

Clarification: We have always had deprecated annotations on our deprecated interfaces, the problem is that we have never clearly communicated when those might no longer exist.

---

When we deprecate an API, we announce the deprecation to our users and keep the deprecated API for two further releases. But to ensure, that everyone knows that the API is deprecated (language is C), we put an #error This module is deprecated since ... in the header that makes the API public.

Keep that state until you finally decide to delete the API.

---

I would say this depends mostly on who uses your API. If your API is used by users you have no control over, you need to be much more careful about changing it. If it's used strictly internally, then it's mainly a QA concern--how can you be SURE nothing is still calling an old function?

A general approach I've taken in some of my (very small) projects has been to adjust our callers to no longer use the old API, then document that the old API functions are no longer supported (possibly with just a source comment, depending on your situation). Then after a full test/release cycle of testing the new API, we'll delete the old functions entirely, and then run through another complete test/release cycle to make sure we didn't miss any hidden callers to the old API.

Depending on the exact API, you might be able to put some debugging code in the old functions, so that you'll find evidence when someone is still using (or erroneously starts using) the old API.

---

In some programming languages/environments you can decorate functions as deprecated or at least insert compiler warnings/messages when they are invoked. This is a good tactic for reminding (bugging?) users to stop using those functions.