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<deprecatedClass> listOfDeperecatedClass

So do I need to add the @Deprecated tag for this list too?

---

Edit: @Deprecated should have a capital 'D'.
See: http://docs.oracle.com/javase/7/docs/api/java/lang/Deprecated.html

Answer 1

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.

Answer 2

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.