Kieran France

Kieran France is a programmer for IDRSolutions. He enjoys tinkering with most things including gadgets, code and electronics. He spends his time working on the the JPedal library and our internal test suite..

4 ways to let go – Knowing how and when to Deprecate methods

2 min read

In the interest of improving usability and maintainability of our PDF search code I have recently been creating a single PDF search method to replace the existing three. The idea is to have a single point to access the search which will call the different behaviours based on the various flags and values passed into the method. This way we can ensure exactly where the functionality will be accessed from and any reported issues and future enhancements have the same access point.

It can be very pleasing to improve the code but it can lead to a few headaches. When do you know it is time to let go?

The new PDF search method is set up and the tests confirm they do not cause any differences compared the the previous methods. The next logical step is to alter the previous methods so they call the new method and just pass on the required variables.

Now the code now has four search methods when I wanted just one.

The problem I see is how to handle the deprecation of methods. There are pros and cons to the different ways to handle deprecated methods.

1. Abra Kadabra and it’s gone.
The methods could always just disappear over night. The methods could be removed fully without warning. Of course I will post something to inform users that they have been removed.

Pros
Don’t need to think of the methods again.
No chance to confusing the methods as of now.

Cons
The multitude of emails asking where the methods have gone.
Possible lose of users due to the lack of thought about their needs.

2. Too many deadlines.
I could always just mark the methods as deprecated and post a date by which it will be removed. This way everyone can work to the same deadline.

Pros
You have a cut off point by which everyone can move across to the new method.
Up until the deadline you can remind users of the change and post tutorials to help.
Users always knwo what is happening.

Cons
On top of your users projects they have yet another deadline.
Possible issues may arise that mean extending the deadline.

3. It never quite dies.
The methods could be marked as deprecated and just left in.

Pros
No need to worry about users moving over. If they don’t have to and it works, why do it?
Current users familiar with the methods will not need to touch the new code.

Cons
You end up with too many methods all for doing the same thing.
If an issue arises in which method was it in? Is it in all or just some of them?
How many time do you need to redo that fix?

4. Sneak up on it.
The methods are marked as deprecated and the documentation is updated without mention of it yet. Those who find this are new users and current users that need to find something in the documentation and search class. At a later point you anounce the change with a deadline.

Pros
Smaller groups of users are exposed the to the change at any one time.
Handling any issues that may arise will be easier with a smaller group.
You can anounce the deadline when you have had time to ensure any isues are ironed out.

Cons
If a user misses the anouncement of the deadline they may be caught out.

So there are the choices – sometimes one method just seems the right way to say goodbye. What is your approach to deprecating methods? How do you let go?

Kieran France

Kieran France is a programmer for IDRSolutions. He enjoys tinkering with most things including gadgets, code and electronics. He spends his time working on the the JPedal library and our internal test suite..

Why you should care about Unicode support in Java…

Here at IDRsolutions we are very excited about Java 9 and have written a series of articles explaining some of the main features. In...
Bethan Palmer
1 min read

Updates to our Text to Speech support in PDF…

Some time ago we introduced text to speech functionality to the JPedal example viewer. This used the FreeTTS library and its default voices with the option of...
Kieran France
1 min read

Three ways to convert PDF to HTML5: Text and…

There are several ways that you can deal with text and fonts in PDF files when converting to HTML5. Here are there are the...
Leon Atherton
2 min read

Leave a Reply

Your email address will not be published. Required fields are marked *