6

I have seen many examples of using the Deprecated annotation on APIs in order to mark them as 'need to be replaced soon'.

However, in almost all of these cases the code developers not only kept using the deprecated APIs, but also suppressed the deprecation warning.

It seems like the best intentions of the API developers end up creating more code which is irrelevant to the implemented business logic - if an API is deprecated but is continually used with the associated warnings being suppressed it seems like a degradation of the code at best and a potential application breaking point when replacing deprecated libraries at worst IMHO.

Is there a practical solution to this problem? At the very least, a way to tag this occurrence as a code smell, if it indeed stays for a relatively long time in the CR?

Please suggest an actual solution you might be using (library, SCA, CR plugin, etc.....)

Are there any planned JRE/JDK features that might help with this situation? My research has currently not found anything.

References:

6
  • 3
    Actually remove the functions after they've been deprecated for a reasonable amount of time. Leaving deprecated functions in your code base is an anti-pattern in and of itself. May 12, 2018 at 4:49
  • 2
    See: openjdk.java.net/jeps/277
    – Jacob G.
    May 12, 2018 at 4:50
  • @ElliottFrisch : Good recommendation, but I do not want to have to follow the life time in code of the deprecated methods. Any thoughts on how to detect a deprecation "time out" automatically? May 12, 2018 at 4:53
  • @RannLifshitz You could add a comment about when you deprecated the method; but ideally you don't have to deprecate many methods. May 12, 2018 at 4:56
  • @ElliottFrisch : How about configuring a SCA server to flag deprecated APIs/deprecated API calls as blocker issues ~6 months after they are inserted into the CR ? May 12, 2018 at 5:06

3 Answers 3

6

Step 1: Announce the removal

One may think that deprecating an API means announcing it will be removed, but this is not the only use case (as described in relevant articles of e.g. Java 7 and Java 9):

  • The API is dangerous (for example, the Thread.stop method).

  • There is a simple rename (for example, AWT Component.show/hide replaced by setVisible).

  • A newer, better API can be used instead.

  • The deprecated API is going to be removed.

To further complicate things, before Java 9, no deprecated API in the JDK was ever removed (see 20 Years Of Java Deprecation), so it is understandable if developers do not take deprecation seriously - neither in the JDK nor elsewhere.

Therefore, you need to communicate clearly that the API is really, really going to be removed. The way to do this depends on the version of Java your API is compiled with.

Java 8 or lower

In these Java versions, there is no formal way to explicitly distinguish the various deprecation use cases. The best you can do is adding the Javadoc tag @deprecated and not only giving the reason of deprecation and listing alternatives, but also explicitly announcing your intention to remove the API.

Java 9 or above

Since Java 9, with Enhanced Deprecation, you can now write

@Deprecated(forRemoval=<boolean>)

to explicitly document your intention. I think that together with Javadoc @deprecated (which should detail the reason for deprecation and list alternatives), this standardized flag is a fair warning.

With this flag set to true, the compiler will warn for each use of the deprecated element like this:

YourClass.java:<line>: warning: [removal] <method> in <class> has been
deprecated and marked for removal

This warning is enabled by default (instead of having to be enabled with -Xlint:deprecation) and is not suppressed with @SuppressWarnings("deprecation"). Instead, one would have to suppress it with the new @SuppressWarnings("removal"), which might make developers think twice about doing so without a really good reason.

Additionally, you can explicitly state the library version which introduced the deprecation with

@Deprecated(since="<version>")

Seeing this in Javadoc or the sources can help developers assess how urgent it is update their code.

Step 2a: Runtime warning

If feasible for the situation, add a runtime reminder: when the deprecated API is used, have it log a warning to the console or log file (using whatever logging mechanism you use) announcing that this will no longer work with the next major release. To avoid spam, you could only log that once (e.g. private static boolean warningLogged).

Step 2b: Static code analysis

Static code analyzers like SonarQube (also available as a hosted service) can be set up to flag each of these warnings. The SonarQube rule "deprecated code should not be used" should even work if the compiler's deprecation usage warning is suppressed.

SonarQube also tracks when a certain issue (i.e. a rule violation) was introduced (based on version control) and you can interactively filter its issue lists based on that date. For example, you could list all usages of deprecated code that have been in your code base for over a year so that you can prioritize work on fixing them.

Step 3: Remove the API

Not actually removing the API would give your API users the impression that they don't need to bother changing their code.

2
  • 2
    Very nice, +1. This is exactly what forRemoval=true is intended for. Note in addition to the warnings having different text, such "removal" warnings are now enabled by default (instead of having to be enabled with -Xlint:deprecation; and also the removal warnings are not suppressed with the typical @SuppressWarnings("deprecation"). (They can be suppressed with @SuppressWarnings("removal") but anyone who does that bears responsibility for their code being broken when the API is actually removed.) May 18, 2018 at 21:03
  • 1
    Thanks @StuartMarks, I edited the answer to include this. May 19, 2018 at 9:35
2

A deprecated API is not useful just as far as it is annotated with @Deprecated. If the API clients can still successfully use it after years of it being marked as deprecated, then it's right to say that the API provider isn't helping them in any practical way.

Is there a practical solution to this problem?

Yes: let deprecation mean deprecation and after a grace period, make the deprecated API unavailable, if removal is the correct way to deal with it. If, for example, you deprecate an API with security risks, not removing it in a future release makes deprecation useless and can be seen as contributing to the problem.

The @Deprecated annotation is little more than documentation, which, even as you noted, other developers can simply ignore.

Java 9+ deprecation is perhaps more informative, but the end decision is still up to the developer consuming the API, which doesn't solve the problem.

8
  • The problem is that Java 10 is expected to be able to run code written for Java 1.0/1.1. If you removed deprecated libraries, you'll get runtime errors on older code.
    – Powerlord
    May 12, 2018 at 5:13
  • 2
    @Powerlord Java as a platform has its own kind of requirement, but that doesn't have to be the behavior for everyone to adopt by default. Unless you also provide a runtime with provided libraries that clients are compiled against and depend on for runtime, the decision to remove deprecated APIs shouldn't be constrained by such a requirement.
    – ernest_k
    May 12, 2018 at 5:19
  • @Powerlord Since Java 9 things have been marked deprecated for removal and those things will get removed in future versions. In other words: some things will break in future Java versions. May 12, 2018 at 15:54
  • @MarkRotteveel Things that have been marked as Deprecated since Java 2 (aka Java 1.2) are still in Java, why would I have any expectation that something marked as Deprecated in Java 9 would be removed any time soon?
    – Powerlord
    May 12, 2018 at 21:32
  • @ErnestKiwele People are resistant to change. If you start removing APIs, I can guarantee you that some people will choose to stick with old, possibly insecure versions of your API just so that they don't have to update their code.
    – Powerlord
    May 12, 2018 at 21:36
2

Is there a practical solution to this problem?

Practical from whose perspective?

From the perspective of developers who routinely ignore / suppress deprecation warnings, they already have their "solution" ... which is to ignore the problem. But the flipside is that other people can't stop them from doing that. But the flipside of the flipside is that ... ultimately ... it is not other peoples' business.

From the perspective of developers who wish to deprecate the APIs that they maintain, they already have a solution. Just do it. Then follow through with the next step by actually removing deprecated APIs. The flipside is that it will annoy some people, and other people will be burned. (Especially people who routinely ignore / suppress deprecation warnings. But see above: that is their problem.)

From the perspective of someone whose concern / responsibility it is to maintain the code quality / integrity of an organization's codebase, yes there is a problem. But the solution is relatively strait-forward:

  • Forbid code the use of @suppress("deprecation")`.
  • Forbid build scripts that turn off deprecation warnings.
  • Enforce the above in via SCI server plugins, custom style-checker rules, or (if you want to be crude) by "grepping" the source code.
  • Take a (metaphorical) big stick to programmers who are repeat offenders.

Are there any planned JRE/JDK features that might help with this situation?

As noted, Java 9+ enhanced annotation support (see JEP 277):

  • provides more informative deprecation tagging, and
  • provides a tool (jdeprscan) for scanning for deprecation violations against the Java SE APIs.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.