Ideas on how to use Java’s deprecation features:
DON’T deprecate because you intend to re-write at some point. Wait until you’ve actually produced the replacement or at least know when the replacement will be available. Marking all code you’re displeased with doesn’t help anyone, use “TODO” comments or something else for that.
DO document what alternative to the deprecated code to use instead.
DO document why the code is deprecated. It could be from everything from aesthetic to important security reasons, so your users may want to know.
DO, if possible, re-implement deprecated code in terms of its replacement. This will both ensure that things continue to work and instruct how to update calling code.
DON’T use deprecation if all callers are within your own code base. Just update the callers and remove the code.
DON’T deprecate a method if there’s no real alternative. E.g. if you know a method is needed but don’t like that it breaks encapsulation you can discourage its use in documentation, but if you use @deprecated all calling code will be plagued with useless warnings.
