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.
Java Deep 
As to rule #2: Sounds correct, in theory, but in real life, one day a reason for updating a library comes up, and shortly thereafter a different reason comes up for looking into a different piece of code, and then there’s that call to a now-deprecated method that doesn’t even say what it’s doing anymore. Just because a method has been deprecated you shouldn’t impose unnecessary difficulties on people who still use it for whatever reason. A reason that might even be sensible 😉
LikeLike
If there is difference between theory and real life, then probably there is some problem with the theory. Or, for that matter, with the real life.
First of all: the documentation is still there in the old version of the library. Have a look at that.
Second: there is a working code that should fairly explain the usage of the method. If it does not, then this is not the lack of JavaDoc of the deprecated method the difficulty but rather the non clean code.
Finally: if I, as a developer of a library encourage the users (my customers) to use a deprecated method providing the outdated information I do harm to them. Never harm the customer.
LikeLike
You asked for the flamewar 😉
1. In my example, which is a real-world example, there is no old version of the library in the project. Having to search elsewhere makes the job more time-consuming and thereby more costly.
2. Having to analyze the code that uses the method in order to determine what it does is, even in a best-case scenario, more time-consuming and thereby more costly.
3. I, being a developer and, as such, customer when it comes to libraries, do not need nor want library developers to discourage me of something by inconveniencing me, which is decidedly paternalizing, too. To mark a method as deprecated by annotation and/or JavaDoc is absolutely sufficient to make the point. And as a matter of fact, I have never been harmed by existing documentation for deprecated methods, and I’ve encountered some in my life. I have, though, been more than once inconvenienced, i.e. harmed, by absent documentation for a deprecated method in a library I had to use the latest version of, while, at the same time, refactoring the code to get rid of the deprecated method was not an option…
LikeLike
>You asked for the flamewar
I know 😉
LikeLike
1. If there is no old version of the library, then you should not use any deprecated method when you start to use the current version. If there “was” an old version of the library but currently it does not exist any more then your release management is not professional. “Having to search elsewhere” in this case means to search exactly at the place where the documentation should be.
2. You need not analyze the code. Just read it. No documentation can be more precise than that. You want to understand what the code does in order to maintain that. How would you achieve that without understanding the code itself?
3. You want it or not this is actually what happens when you use libraries and programming languages. You can access private variables via reflection, but this is made inconvenient. You can fluent methods but only in a specific order. You can convert in Java a `long` to `Double` but only through `double`. They are all inconvenienced.
To get rid of a deprecated method is always an option. It is a matter of cost. If the library is not usable without the deprecated method, then the library is not well designed. Consider getting rid of the library.
LikeLike
although a couple of months late, nevertheless … 😉
@1: “there is no old version in the project“. As I understand it, and experience it in engineering projects, there is reluctance to maintain several third party libraries. Its a difference if you have 10 libraries only, or 3 versions of each library. This does not mean that “the truth is not out there 😉 “, just its not policy to keep it alongside the project for good reasons. So, if an old method is still there, it should be documented. Deprecation tells you its not recommended for use anymore, and eventually to be replaced or removed. This does not automatically make it true in client code.
@2 Not a sensible counter argumentation IMO. It might apply if source code is available, well written and is easy code or boiler-plate stuff. Parsing through modified versions of optimized DCT code is not fun, and why one set of parameters was replaced with another. Thats what documentation is for. By extension, if documentation cannot keep up, there is no reason to do it in the first place, as the argument “everyone can just read the source code” still applies.
@3 Probably a question of severity. For example, while applicable for security relevant code, a lot of deprecation is along with enhancements, that are at all not relevant to the client at that point. Therefore, this influences the importance, and further, the inconvenience the user will go through to push those changes.
That being said, in our development cycles deprecation is usually considered a middle step we try to minimize in time, and often not worth doing at all. In development version, we just remove the method, forcing user to comply. Its rude but it works (anyone can patch it back in). For stable versions, adapting the documentation is as weak or strong as using an annotation.
LikeLike
I read from your comment that, perhaps your interpretation of deprecation is a bit different. I feel that when you say a method is deprecated it is a kind ask of the users (library using developers) not to use it. In my reading it is a harsh command: you should not use it. It is only there for the old code so that some code which is not modified at the moment may still be “linked” with the new version of the library.
It is not a problem that we see the world different. It would otherwise be boring. Setting the topic to something that people think different just seeds the discussion that is the real value of a blog article. I appreciate your comments and thank you for adding value to the article for the commoon good of the community.
LikeLike
Pingback: Unit test deprecated methods | Java Deep