How to deal with obsolete library functions?

Question

I am working on a Java library and want to remove some functions from it. My reasons for this are the open API and design cleanup. Some objects have setters, but must be immutable, some functions were implemented better / cleaner in different methods, etc.

I marked these methods “obsolete” and would like to remove them eventually. At the moment, I am thinking of removing these after a few sprints (two-week development cycles).

Are there any “best practices” for removing redundant shared code?

/ JaanusSiim

Answer 1

Set the date and post it in the @deprecated tag. The amount of time it takes to delete depends on the number of users of your code, how well you are associated with them, and the reasons for the change.

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

If your users are your 10 employees and you see them daily, time frames can be easily accessed over a range of weeks.

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

Answer 2

Think of it this way, Client A downloads the latest version of your library or frame file. It gets compiled on this machine, and suddenly it sees thousands of errors because the member file or function no longer exists. From that moment, you gave the client a reason why you do not need to upgrade to the new version and stay with the old version.

Raymond Chen answers this best on his win32 API blog.

Although our experience at our home software was, once the API was written, we must carry the API until the end of the product life cycle. To help users with new versions, we provide backward compatibility with old teams in the new structure.

Answer 3

It depends on how often the code is restored. For example, if there are 4 applications in the library and they are rebuilt daily, a month takes enough time to fix outdated calls.

In addition, if you are using an outdated tag, provide some comment by which the code replaces the outdated call.

Answer 4

Use the @ deprecated tag. Read the API Rejection document for more details.

After everyone using the code informs you that they have cleared on their side, start deleting the obsolete code and wait and see if someone complains and then tell them to fix their own code ...

Answer 5

Given that this is a library, consider archiving a version with legacy features. Make this version available both in source code and in compiled form, as a backup solution for those who have not upgraded their code for your new API. (The binary form is needed because even you may have a problem compiling the old version in a few years.) Make it clear that this version will not be supported and improved. Mark this version with a symbol in your version control system. Then move forward.

Answer 6

Of course, it depends on the extent to which your API is used and what you promised upfront to your customers.

As described by Vinko Vrsalovic, you must enter a date when they should expect the function to be abandoned.

In production, if it is “just” a matter of getting cleaner code, I usually leave things in place even after an outdated date if it doesn't break anything.

On the other hand, in development I do it immediately to quickly figure it out.

Answer 7

You might be interested in examples of how deprecation works in some other projects. For example, it follows here that the policy in the Django project is to deprecate functions :

A small version may spoil some features from previous releases. If the function of version AB is deprecated, it will continue to work in version AB + 1. In version AB + 2, using this function will cause PendingDeprecationWarning, but will continue to work. Version AB + 3 will completely remove this feature.

Answer 8

too bad you are not using .Net :(

The built-in Obsolete attribute generates compiler warnings.