What process/guidelines should be followed, when I am about to deprecate a few methods from my service classes in Java?

Question

My team plans to deprecate a few methods from a specific library.

I do not want to simply remove them, but dont want to return results either from the mehtods that are to be deprecated.

What are the guidelines/process I should ideally follow?

Answer 1

Ideally I don't think you want to sabotage the existing methods. Understand what deprecation is for:

You have methods you no longer wish to maintain for whatever reasons--better alternatives, security problem, etc. Problem is you have existing users that need time to migrate to the new API. Deprecation is the process of notifying your users that there is a new API and the old one will no longer be supported.

When you deprecate a function the first time, you will piss off a bunch of your users if you completely disable it right off the bat. Their users will start complaining how the app suddenly broke and all they did was update your library for the new features. (Users don't always think these things through). So follow this process:

• In the first release deprecating a method, mark it as deprecated with the annotations and document in the Javadocs what people should be using instead. It also helps to document why it was deprecated, particularly if it is a security concern. Also specify that the method/function will no longer be maintained after this release. That gives people time to migrate.
• If the method is particularly problematic (like Java's Thread.stop()) or a major security concern, disable it in the next release after the deprecation. By disable I mean throw an exception. If it's Java throw something that extends Error because it is dangerous to use.
• If the method is not problematic, keep it around for another release or two, but only maintain it enough to compile. Don't put any more effort into it than that. Remember, you are not promising to maintain the function anymore.
• Finally, when you've had a couple releases with the function marked as deprecated, you can completely remove it. Everyone should have had enough time to migrate off (at least give them six months, as some projects are slower to update than others).

Answer 2

Apart from from the "@Deprecated" annotation, I would add to javadoc why it is beeing deprecated, alternatives to use, and define a period for keeping it that way. After that period, changing the method to throw an exception with a message saying the method "B" as been deprecated and no longer works.

Simply removing the methods or adding that exception is not a good ideia because many programs will start to fail, I usually signal them as deprecated, and just don't do any updates or bug corrections on them. Deprecated is just that, "the method won't be updated anymore"

Other projects will start to get warnings about using a deprecated method, so sooner or later, things will be corrected.

Answer 3

I think there is no general rule that applies to all scenarios here.

It depends a lot of who the users of the library are. The smaller the user base is and the closer the user base is to you and your team and the more chance you have to influence the applications using your library the more "aggressive" you can be in changing your public API.

When changing the client code is relatively easy you could explicitely document "this method is deprecated in version 1.x and will be removed in version 1.x+1. Of course this only works if the clients are able to follow your changes. If you don't know the clients that well you might be forced to keep the API stable for future generations to come and need to keep the methods for the sake of compatibility until version 1.x+10.

The key here is communication - when everybody knows what happened in a release they can adapt to it.