As part of a refactoring effort or just ongoing development, a particular method or maybe an entire class may become obsolete in some sense. Java supports the @Deprecated annotation to indicate that there's probably a better way to handle the functionality in question. I imagine this is particularly useful in public API's where the effects of removing parts of an API might not be known. For a non-public API and a project that uses revision control systems (so deleting can be undone in some sense), when is it appropriate to deprecate rather than deleting the obsolete element(s)?

3 Answers 3


Is your API a public facing API? That dictates whether or not you should deprecate or remove. If the API is strictly for your benefit (i.e. only used within your company), then it is best to simply remove the offending code. It's much cleaner and will cause fewer maintenance headaches in the long run.

However, if the API is public facing simply removing a method can cause code that used to work with older versions of your library to stop working. That's where things get messy. The following are some guidelines:

  • Internal API: remove rather than deprecate. If any client is using an internal class or method, it is their fault if the tool breaks.
  • External API: deprecate first, remove later. Deprecation is a flag that something will be removed later. Later depends on what you believe is reasonable. At the very least give 2-3 versions before actually removing the deprecated code.

It's probably a good idea to set up a reminder when you @deprecate a class or method. You're doing it to promote its obsolescence. So make a guess at how long it will take, as a spare time, as-you-get-to-it, task, to eliminate all references. Mark it as @deprecated and put a reminder in your calendar. When you get the reminder, check. If it's no longer used, delete it. If a couple of references remain that can be quickly updated, do that and delete the item. If more significant work remains, bump your reminder forward a bit.

Do this enough times and you'll develop a feel for how long it takes to get rid of a class or method in your projects.

  • 1
    +1 but rather than your calendar, perhaps the team technical debt repayment calendar would be more appropriate?
    – Gary
    Commented Apr 14, 2011 at 8:02

IMHO if you can ensure that noone is using it and never will, just remove it. (This can be tricky in the presence of reflection, or external components such as Velocity macros - modern IDEs such as IntelliJ can find references in e.g. JSP but not via reflection or in Velocity.)

If there is a better alternative but the old one is still used in a lot of places, and you currently don't have time to refactor all client code, it is adequate to @deprecate the obsolete class/method (with an adequate comment about the favoured alternative).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.