85

There are at the moment, two ways to mark code as depreacted in java.

Via JavaDoc

/**
 * @deprecated
 */

Or as an annotation:

@Deprecated

This is my problem - I find it a bit too much to declare both, when marking a method as deprecated when using Eclipse. I really just want to use one of them.

However does using the annotation give the compiler actual useful additional information?

But only using the annotation, I cannot state why the method is deprecated - I can only do that with JavaDoc, and deprecating a method without specying why is bad.

So, can I only use one of them? Or should I really just learn to specify both?

Langusten Gustel
  • 10,917
  • 9
  • 46
  • 59
corgrath
  • 11,673
  • 15
  • 68
  • 99
  • 4
    What if the other programmer doesnt have your sources? He will not know that your method is deprecated. I would say use annotation @Deprecated – Eduard Feb 18 '11 at 09:48
  • 1
    @t-edd: if the other programmer doesn't have either the sources or the javadocs (which displays annotations as well), accidentally using deprecated APIs is the least of this problems. – Michael Borgwardt Feb 18 '11 at 09:58
  • 1
    @ Michael Borgwardt I was just trying to elaborate on what problems could it bring. And this is only one I could come up with. Sometimes you can omit downloading sources and javadoc and use deprecated api which will not be present in next version... – Eduard Feb 18 '11 at 10:04

5 Answers5

80

You should use both. The Annotation allows the compiler to display a warning whenever a deprecated method is used, and the javadoc explains why. Both are important.

As per Oracle's Java Annotations tutorial:

When an element is deprecated, it should also be documented using the Javadoc @deprecated tag...

sheldonh
  • 2,684
  • 24
  • 31
Rawrgramming
  • 1,445
  • 14
  • 15
  • 5
    However, the Oracle compiler will display a warning for the javadoc tag as well, so the annotation is not really needed. – Michael Borgwardt Feb 18 '11 at 09:56
  • @Michael - in many cases (but not all I'd imagine), this can be controlled with `@SuppressWarnings("deprecation")` – luis.espinal Sep 17 '11 at 15:18
  • 4
    @MichaelBorgwardt I understand your thinking, but too much of that eventually leads to "don't write documentation anyway, because you can only trust source code". The javadoc annotation does serve a purpose, for example, it is the only place where one can direct the user to "use this replacement instead". – Edwin Buck Aug 26 '13 at 14:12
  • 4
    Amen Edwin. The fact that 2 notations are required sucks though. – ggb667 Sep 13 '13 at 17:30
  • 1
    @MichaelBorgwardt [Since JDK 9](https://bugs.java.com/bugdatabase/view_bug.do?bug_id=JDK-8164073) javac complains if the Javadoc tag is used without the annotation. Makes sense since another compiler may just check the annotation. – Martin Jan 31 '19 at 15:40
37

From the horse's mouth:

NOTE: The Java Language Specification requires compilers to issue warnings when classes, methods, or fields marked with the @Deprecated annotation are used. Compilers are not required by the Java Language Specification to issue warnings when classes, methods, or fields marked with the @deprecated Javadoc tag are accessed, although the Sun compilers currently do so.

So basically, if you want a guarantee that there will be compiler warnings, you need to use the annotation. And because of some API designer's breathtaking incompetence, you need to specify the javadoc tag as well to give an explanation.

Personally, I'd say the annotation is useless and should be omitted until it's fixed, since any good compiler or IDE will display warnings with the javadoc tag as well.

Michael Borgwardt
  • 342,105
  • 78
  • 482
  • 720
  • 3
    "since any good compiler or IDE will display warnings with the javadoc tag as well." And any decent programmer will not rely on the compiler to tell him about deprecated stuff, he'll look for documentation of new or changed APIs. – jwenting Feb 18 '11 at 10:45
  • 13
    @jwenting, looking for documentation is a waste of a human's time. Make the machines figure out if something alarming is going on and tell you about it. That's their job. – thejoshwolfe Aug 20 '11 at 07:04
  • 1
    @josh no, it isn't. The programmer should know what he's doing, create code with as little things for the compiler to complain about as possible. It's a fallacy that the programmer shouldn't know anything, that the compiler should do everything for him. Were that the case, there'd be no need for the programmer, the compiler would read the functional specs in human language and translate them to a perfect piece of software automatically. – jwenting Aug 22 '11 at 05:26
  • 2
    @jwenting I disagree. Annotations and javadocs ARE a way for the programmer to "know" about the APIs. It's a valid form of documentation. Whenever possible, the programmer should use his/her brainpower to think about interesting stuff, not to hunt down documentation from who knows where. – Andres F. Feb 10 '12 at 18:53
  • @AndresF. no. A programmer who needs to look at the documentation for everything (rather than obscure details) is a poor programmer. He doesn't understand what he's doing, he's slow, he's prone to errors that an understanding of the language and its idioms would prevent. – jwenting Feb 12 '12 at 07:36
  • 2
    @jwenting: Weren't you the one stating that "any decent programmer [...] look for documentation" above? Besides what about existing code? How does your superpowered programmer deal with APIs that become deprecated yet may or may not be used throughout code written before that? Your statements here are bordering on the inane. – Michael Borgwardt Feb 12 '12 at 11:44
  • @MichaelBorgwardt the programmer shouldn't need the documentation for the basics, the compiler shouldn't need to be predictive as to the programmer's intent. The two aren't mutually exclusive. – jwenting Feb 13 '12 at 06:43
  • 3
    @jwenting: OK, but how is the fact that a specific API is deprecated part of the basics? And how are compiler warnings indicating the use of deprecated APIs in a body of code "predictive as to the programmer's intent"? – Michael Borgwardt Feb 13 '12 at 09:57
  • 10
    I suppose the best thing would be if the @Deprecated annotation could support a string 'value' which could accept an explanation of why the deprecation is in place. The explanation seems to be the only reason one would use the javadoc way instead of the annotation itself. – jrharshath Jan 22 '13 at 13:46
  • "API designer's breathtaking incompetence" - You've basically surmised everything Java, from the language to the included libraries to the third party libraries to all the tools around it to the project leads who decide to use it. – ArtOfWarfare Oct 06 '17 at 16:22
  • @ArtOfWarfare that kind of mindless bashing only makes yourself look stupid. – Michael Borgwardt Oct 06 '17 at 19:33
9

You should write both. The @Deprecated Anotation is for the Compiler and the @deprecated JavaDoc tag is for the Person who wants to know why this is deprecated.

An example can look like this:

/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}
Marcel
  • 1,606
  • 16
  • 29
  • 2
    For the compiler? The compiler doesn't care other than to issue warnings to the developer, so they're both for the developer. It's just that the annotation is nearly useless by itself, while the javadoc comment is not guaranteed to be used. So Sun/Oracle (I don't know whose watch this was on) set up a situation where developers have to do two different things to adequately document the situation when one should have been sufficient. – nasch Apr 05 '15 at 01:18
  • Both of these answers are spot on. You should use both but should only need to use one. – thonnor Jul 20 '15 at 15:53
6

You should specify both.

The annotation lets the compiler know about it and trigger warnings when the method is used. The JavaDoc attribute lets developers know about before they start using it.

These are two very different things!

Dunaril
  • 2,757
  • 5
  • 31
  • 53
  • 6
    These are not different things at all. If the annotation allowed an explanation as parameter, that could be displayed to developers as well. – Michael Borgwardt Feb 18 '11 at 09:55
  • @Michael Your own answer emphasizes the difference between them. Actually it even develops on the same idea as mine. – Dunaril Feb 18 '11 at 10:03
  • 5
    no, my answer emphasizes that the javadoc tag is still needed only because the annotation was designed badly. Annotations are code metadata and information for developers just like method sigantures. – Michael Borgwardt Feb 18 '11 at 10:08
  • 2
    Needing 2 tags is stupid. The annotation should not exist because without the documentation it is next to worthless. In fact right now I am wondring why this particular thing is marked deprecated. There is no @Deprecated javadoc tag, so I have no idea. This sucks. It's almost worse than nothing, because someone at sometime said "don't use it", but not why. Urge to strangle rising. – ggb667 Sep 13 '13 at 17:32
1

This can be easily dealt with a good IDE.

Eclipse Neon, for eg. automatically adds @Deprecated annotation, when I create a javadoc @deprecated on a method or field.

So I simply write the javadoc with the appropriate explanation and let the IDE take care of adding the @Deprecated annotation, the minute I save the file.

Inxsible
  • 700
  • 5
  • 27