How to annotate deprecation of a class in Java?

Question

I am going to deprecate a class in Java.

@Deprecated
class deprecatedClass

and I have list of this deprecated class,

List&         


        

Answer 1

Do you have operations on the List as part of your public interface? In that case, mark all those methods as deprecated too. Otherwise you should be fine.

Answer 2

Just marking as:

@Deprecated
List<deprecatedClass> listOfDeperecatedClass

Should be okay.

Answer 3

You only need to add the deprecation message to the declaration of anything you are deprecating. It serves as a warning that people should avoid an implementation which uses the deprecated class, such as in List<DeprecatedClass>.

Answer 4

No, you don't need to. Adding the annotation @Deprecated to DeprecatedClass will generate a warning every time it's used.

---

What you should do however, is marking methods in other classes that take your deprecated class as an argument or return it, as deprecated as well. That goes for any access that other code may have to instances of your deprecated class — public fields, constants and so on. Those of course can't be used without an instance of your deprecated class, so the warning is given anyway, but in a correct deprecation annotation and comment, you should provide an explanation and point to an alternative, which is valuable information you need to give.

A method signature is like a contract and so is a class signature. You're telling other programmers what methods they can call and how they can call them. You're telling them which fields are accessible. Other programmers base their code on that. If you really need to break that contract, you first need to provide a substitute for that contract (a new method with the same functionality), and tell them and give them time to switch to that new contract (deprecate the old methods and classes).

Of course, the above assumes that you're coding to an audience. If you're the only one using your code and you just want to deprecate to clean up your code without breaking the build, just deprecate the class, fix the warnings, and remove it.