Should I use JavaDoc deprecation or the annotation in Java?

java annotations javadoc deprecated

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?

What if the other programmer doesnt have your sources? He will not know that your method is deprecated. I would say use annotation @Deprecated

@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 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...

sheldonh

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...

However, the Oracle compiler will display a warning for the javadoc tag as well, so the annotation is not really needed.

@Michael - in many cases (but not all I'd imagine), this can be controlled with @SuppressWarnings("deprecation")

@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".

Amen Edwin. The fact that 2 notations are required sucks though.

@MichaelBorgwardt Since JDK 9 javac complains if the Javadoc tag is used without the annotation. Makes sense since another compiler may just check the annotation.

Michael Borgwardt

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.

"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, 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.

@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.

@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"?

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.

Marcel

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(){..}

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.

Both of these answers are spot on. You should use both but should only need to use one.

Dunaril

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!

These are not different things at all. If the annotation allowed an explanation as parameter, that could be displayed to developers as well.

@Michael Your own answer emphasizes the difference between them. Actually it even develops on the same idea as mine.

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.

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.

Inxsible

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.

Should I use JavaDoc deprecation or the annotation in Java?

Follow WeChat

Want to stay one step ahead of the latest teleworks?

相似问题

Platform

Support

Contact US