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.
Don’t need to think of the methods again.
No chance to confusing the methods as of now.
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.
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.
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.
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.
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.
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.
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?
IDRsolutions develop a Java PDF library, a PDF forms to HTML5 converter, a PDF to HTML5 or SVG converter and a Java Image Library that doubles as an ImageIO replacement. On the blog our team post about anything interesting they learn about.