What is the best way to comment a deprecated class in Java?

Question

I would like to know the best way to add a comment to identify a deprecated class in Java. Should I remove the previous comment added to the top of the class that helps another programmer to know what was that class for, or should I add it below the comment?

Answer 1

The recommended approach to deprecating a class, method, or field in Java is to use the @Deprecated annotation, which became available in Java 5, or the @deprecated JavaDoc tag, which has been around since Java 1.1. Oracle has a document about the specifics on how and when to deprecate APIs that appears to be relevant.

Should i remove the previous comment added to the top of the class that helps another programmer to know what was that class for or add it below the comment?

You should not edit or remove any existing comments, other than to add the JavaDoc tag or annotation. Deprecated code might still be in use in legacy systems, and developers of those systems need to have access to the documentation that the original developers did in some form.

Answer 2

As Thomas Owens pointed out, we should always use the @Deprecated annotation (available since Java 5) or the @deprecated JavaDoc tag (available since Java 1.1). In addition, Oracle has relevant documents (for each version) that explain the syntactic details on how to use these tags (e.g. https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/deprecation/deprecation.html). Some have recommended that we should use both tags, and I agree.

However, nobody at Stack overflow or anywhere else--with the exception of Stephen Gelman in one of the hidden comments--has pointed out the important semantic information that needs to added when we deprecate a class, field, or method:

"ALWAYS, ALWAYS, ALWAYS (emphasis mine) add a @see tag with the method(s) superseding the deprecated method! It can be unbelievably frustrating to figure what method should be used instead. Especially if the method is in another object."

Alternatively, I would recommend using the @link tag (there seems to be quite a bit of unresolved discussion on the merits of @see and @link, and on how to use both; sometimes the answer depends on which IDE you are using).

For implementing best practice while deprecating in Java, remember:

We obviously understand why we are deprecating something, but while our code definitely contains what we are deprecating, our replacement is buried somewhere else, and often difficult to find. More importantly, the code does not contain the reason we deprecated something in the first place. So, PLEASE have mercy on the poor software developer who must support your code after you have gone on to greener pastures. PLEASE use the tags to explain why the class/field/method was deprecated, and make sure you mention what you replaced it with.

Answer 3

As @Tihamer says deprecation should be documented via @deprecated and an additional Javadoc. In addition to using the @deprecated Javadoc-Tag, see the official recommendation to use @link or @see:

Include paragraphs marked with @link or @see tags that refer to the new versions of the same functionality.

e.g.

/**
 * @deprecated  As of release 1.3, replaced by {@link #getPreferredSize()}
 */
@Deprecated public Dimension preferredSize() {
    return getPreferredSize();
}

Answer 4

What you do not do is remove any documentation.

Think about it: The class is deprecated so I want to replace all its uses. And I want to do that without breaking anything. To replace uses of the class without breaking things, I need to know exactly what it does, which means I need its documentation.

What you do instead is adding a link to documentation how to replace the deprecated class or method. A link to the replacement may be enough, because often it will be obvious how to use the replacement - if you can find it.

And eventually your deprecated method will disappear. So now everyone still using it is 100% forced to replace it. You might rename class X to deprecated_X (with no other change, people are supposed to remove uses of X) to really give people an incentive to replace it, give people some time to unbreak broken code, then remove it altogether.