11

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?

Thomas Owens
  • 79,623
  • 18
  • 192
  • 283
alculete
  • 213
  • 1
  • 2
  • 5

2 Answers2

19

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.

Thomas Owens
  • 79,623
  • 18
  • 192
  • 283
  • 1
    +1: Using the @Depricated annotations also give a heads up to IDEs like Eclipse to make sure to cross that method out and give other visual hints to developers. – Ryan Hayes Sep 05 '11 at 14:48
  • yes i know how to deprecate and the use off annotation my question is for example i have this code /** * comment about the class **/ public class ClassToDeprecate{ // some code here } should i remove the comment and be like this – alculete Sep 05 '11 at 14:49
  • 1
    @Spammer The article I linked to discusses that. Also, browsing through the Java API documentation answers that. The only thing that you should do is add the `@Deprecated` annotation or the `@deprecated` JavaDoc tag. That's it - nothing else, nothing more. – Thomas Owens Sep 05 '11 at 14:53
  • by the way, the link you gave was very helpfull – alculete Sep 13 '11 at 19:07
  • If I want to add a javadoc as *@Deprecated As of version x.y, replaced by {@link SomeClass}* in my current file's javadoc then what should be the version no. in place of x.y ?? **Let my current version is 1.2 & after CVS checkin it will be 1.3** – Soumyadip Das Feb 06 '13 at 03:52
  • 1
    Adding `@deprecated` JavaDoc tag and description along with `@Deprecated` annotation will give more light into why it was deprecated. So it would be more beneficial to use both rather than just `@Deprecated` annotation. – WarFox Jul 08 '13 at 11:53
  • 1
    And always, always, always 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. – Stephen Gelman May 12 '17 at 16:21
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.

Tihamer
  • 21
  • 2