Use Java annotation deprecated the right way

There is hardly anything more infuriating that seeing a method @Deprecated without a proper documentation. I feel lost. Should I still use the method? Probably that is not the intention of the developer, that is why he/she added the deprecation annotation. Should I use something else? So….

What are the rules using @Deprecated?

Rule #1: do Javadoc how not to

Whenever you deprecate a method create a JavaDoc that tells the programmer how not to use this method any more. Do not only say that “this method is deprecated, don’t use it”. That is exactly what the deprecation annotation and the JavaDoc @deprecated word says. There is no point to repeat it in English. The targeted audience is Java programmer, supposed to know what deprecation means.

Name the new methods, that replace the old one. (Use @link!) This may or may not be enough. The new method will have some documentation that explains how to use it. Do not repeat that (text or meaning) in the JavaDoc. Just do not repeat yourself, documentation should also be DRY. On the other hand you may want to describe how to replace the old call with the new one. You may give hint for the refactoring.

Rule #2: do not Javadoc how to

Remove the old JavaDoc documentation. Some may argue that users who maintain the legacy code may still need that. The fact is that they use an old version of the method in an old version of a library. The documentation in the old version is still there, frozen carved into stone (or rather carved into a release in the repository). The actual version that deprecates the method should not contain the outdated documentation. That would encourage the programmers to keep on using the method. There is one single way to use a deprecated method: not using it. JavaDoc should be current describing only that, as described above in rule#1.

Rule #3: no apology in JavaDoc

Do not explain in the JavaDoc why the method was deprecated. You are a responsible developer. This is your decision. You made your choice. Others have to live with it. Write a blog about the background of the architectural decision if you wish. It may be helpful, but JavaDoc is not the place for it.

Deprecated API JavaDoc is exclusively to explain how not to use.

The emphasis is on how. Not “why not to use it”.

Rule #4: do deprecate

If you feel like needing to deprecate a method: do it! If you are afraid of your users and you do not want to make their life miserable deprecating some method this decision will make your life miserable instead. Do all measures to have an API that will not need deprecation so long as long possible. But if ever something needs to be deprecated: throw it right away. Do not feel guilty why you did not see the future when the api was designed. None of us sees the future perfect. After all, life would be boring knowing the future.

If you are interested on opinions about this topic on stakcoverflow visit the linked page. Or just start a flame war, if you wish, here. I am totally trollerant.
 

Reference: Use Java annotation deprecated the right way from our JCG partner Peter Verhas at the Java Deep blog.
Related Whitepaper:

Bulletproof Java Code: A Practical Strategy for Developing Functional, Reliable, and Secure Java Code

Use Java? If you do, you know that Java software can be used to drive application logic of Web services or Web applications. Perhaps you use it for desktop applications? Or, embedded devices? Whatever your use of Java code, functional errors are the enemy!

To combat this enemy, your team might already perform functional testing. Even so, you're taking significant risks if you have not yet implemented a comprehensive team-wide quality management strategy. Such a strategy alleviates reliability, security, and performance problems to ensure that your code is free of functionality errors.Read this article to learn about this simple four-step strategy that is proven to make Java code more reliable, more secure, and easier to maintain.

Get it Now!  

Leave a Reply


+ 4 = ten



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books