How to handle functions deprecation in library?

Question

I'm working on a Java library and would like to remove some functions from it. My reasons for this is public API and design cleanup. Some objects have setters, but should be immutable, some functionality has been implemented better/cleaner in different methods, etc.

I have marked these methods 'deprecated', and would like to remove them eventually. At the moment I'm thinking about removing these after few sprints (two week development cycles).

Are there any 'best practices' about removing redundant public code?

/JaanusSiim

Answer 1

Use @deprecated tag. Read the Deprecation of APIs document for more info.

After everyone using the code tells you they have cleaned up on their side, start removing the deprecated code and wait and see if someone complains - then tell them to fix their own code...

Answer 2

It depends on how often the code is rebuild. For example, if there are 4 applications using the library, and they are rebuild daily, a month is a long enough time to fix the deprecated calls.

Also, if you use the deprecated tag, provide some comment on which code replaces the deprecated call.

Answer 3

Consider it this way, customer A downloads the latest version of you library file or frame work. He hits compile on this machine and suddenly he see thousands of errors because the member file or function does no longer exist. From this point on, you've given the customer a reason why not to upgrade to your new version and to stay with the old version.

Raymond Chen answers this the best with his blog about win32 API,

Though, our experience in our software house has been, once the API has been written we have to carry the API to the end of the product life cycle. To help users to new versions, we provide backwards compatibility with the old commands in the new framework.

Answer 4

Set a date and publicize it in the @deprecated tag. The amount of time given to the removal depends on the amount of users your code has, how well connected you are with them and the the reason for the change.

If you have thousands of users and you barely talk to them, the time frame should probably be in the decades range :-)

If your users are your 10 coworkers and you see them daily, the time frame can easily be in the weeks range.

/**
 * @deprecated
 * This method will be removed after Halloween!
 * @see #newLocationForFunctionality
 */

Answer 5

Given that this is a library, consider archiving a version with the deprecated functions. Make this version available in both source code and compiled form, as a backup solution for those who haven't modernized their code to your new API. (The binary form is needed, because even you may have trouble compiling the old version in a few years.) Make it clear that this version will not be supported and enhanced. Tag this version with a symbolic symbol in your version control system. Then move forward.

Answer 6

too bad you are not using .Net :(

The built in Obsolete attribute generates compiler warnings.

Answer 7

It certainly depends at which scale your API is used and what you promised upfront to your customers.

As described by Vinko Vrsalovic, you should enter a date when they have to expect the abandon of the function.

In production, if it's "just" a matter of getting cleaner code, I tend to leave things in place even past the deprecating date as long as it doesn't break anything.

On the other hand in development I do it immediately, in order to get things sorted out quickly.

Answer 8

You may be interested in examples of how deprecation works in some other projects. For example, here follows what the policy in the Django project for function deprecation is:

A minor release may deprecate certain features from previous releases. If a feature in version A.B is deprecated, it will continue to work in version A.B+1. In version A.B+2, use of the feature will raise a PendingDeprecationWarning but will continue to work. Version A.B+3 will remove the feature entirely.