24 May 2007

Why the @Deprecated annotation sucks

Usually when I want to remove a method and I don't have access to all the client code easily, I start by putting the @depreacted javadoc tag like this:

/**
* blablabla.
*
* @deprecated use foo.bar.MyClass#method instead
*/
public void oldMethod() {}

I try to give a clue of what should be use instead of this method to help my fellow developers.

I wanted to do the same but with the new @Deprecated annotation But you can't pass a string to it!

I couldn't believe it, just adding a simple string parameter... and I'm not the only one:

Is the @Deprecated annotation more useful than @Override? I think not. The annotation doesn't support any arguments, so unlike the Javadoc tag you can't provide a string to explain the deprecation and recommend an alternative method to use. The @Deprecated annotation actually provides less value than the @deprecated tag. The only advantage with the annotation is that you can programatically detect deprecated items at runtime. For that reason, conventional wisdom says to use both the @deprecated tag and the @Deprecated annotation, one for documentation and the other for runtime reflection.


Ok the @Depreacted annotation will be pick up by any compiler whereas the javadoc tag will only be pick by modern/intelligent IDE (but most people use eclipse so this point is not really important)


Adding twice the same info (deprecated) is a leap backward to me :(


Technorati tags:

3 comments:

Nicolas said...

A leap backward ? You already explained what is the technical difference between the two tags : "@Depreacted annotation will be pick up by any compiler".

And about the use, effectively it seems redundant. But don't forget that one is about programming/algorithm/API specification, and the other is about the documentation. What would you think about the redundancy of the parameters ? The names of the parameters are used twice. And in fact one defines the parameter, and the second refers the first one to defines its documentation. We can view the "deprecated" tags the same way. One defines that the function is deprecated, the other documents it.

So there is some redundancy (due to the referencing), but no "sucks" for me.

chubbard said...

Drop a bug on Sun. No @Deprecated sucks. There was no thought put into it by the Sun engineers and it should have a parameter to specify a message to what you should use in it's place. maybe even the ability to provide a class and method you should look to. That would allow tools like javadoc to use the annotation.

This is just another example of Sun engineers coming up with a good idea, but poor execution and application of the technology. It's all over the place with Sun created java APIs. Note to Sun: It's not just enough to have a cool architecture. You have to DO SOMETHING WITH IT WITH IT THAT'S MEANINGFUL

Vivjha said...

@Deprecatd helps compiler to generate warning message irrespective of JVM vendors period. There is no other benefit. SUN/ORACLE should put some more thoughts on method usability before lending it to user. Completely agree with you, it should have a String parameter at minimum.