Alternative suggestion for JEP 277 "Enhanced Deprecation"

[Talden]

Your three identified limitations in the blog are a lack of Extensibility,
incomplete absorption of the @deprecated Javadoc tag due to the lack of a
description field and the inappropriateness of the term 'deprecated' for
concepts such as lacking implementation or an implementation/signature
being experimental.

One thing to consider is the retention of the annotation, since that also
retains the fields of the annotation - for better or worse, this is a
atomicity of retention of the platform. Deprecation wants to be retained,
at least, until class-load but there's no mechanism for partially retaining
deprecation detail.  Therefore you're proposing bringing in arbitrary
strings for 'name' and adding per-annotation-site 'description' strings.

Another thing is to consider that the JEP authors have likely considered
the mismatch of 'deprecated' and 'experimental' but are aiming avoid
consuming a term that libraries might already have in use - a less serious
issue than if Java grew new keywords every version that meant methods,
variables and parameters that were once legal now had to change but still a
frustrating source issue requiring one or the other participant to become a
fully-qualified name.

I agree they've overlooked OPTIONAL in their enum as I can see this as
something worth including for several projects. This could enable a
compatibility strictness check to be performed (Long-Term-Service versions
of libraries should have expunged any use of deprecations including uses of
optionals unless those libraries are also supported over the service-range)

I'd have also liked a 'removal' equivalent to 'since' that drives some
urgency around migration from using deprecations (and potentially lends
itself to automating a threat-assessment in relation to platform and
library version use).  Obviously this field might not be set initially or
be changed in platform/library updates as schedules adjust.  It should be
documented as setting an expectation, not declaring any enforcement.

Extensibility is one I don't have a solution for, other than to wonder why
extensions wouldn't simply be achieved through additional annotations if
they're so different from this interpretation of @Deprecated.

--
Aaron Scott-Boddendijk


On Wed, Dec 30, 2015 at 3:08 AM, Lukas Eder <lukas.eder at gmail.com> wrote:

> Hello,
>
> I've recently discovered JEP 277, which is a very good move forward for the
> JDK, but in my opinion not really optimal for the Java ecosystem as a whole
> - as it responds only to a limited set of requirements that are mostly
> beneficial to the development of JDK 9, I assume.
>
> I have suggested an alternative approach in this blog post here:
>
> http://blog.jooq.org/2015/12/22/jep-277-enhanced-deprecation-is-nice-but-heres-a-much-better-alternative
>
> It essentially consists of adding a more generic @Warning annotation,
> roughly like this:
>
>     public @interface Warning {
>         String name() default "warning";
>         String description() default "";
>     }
>
> Which could then be used on JDBC:
>
>     public interface ResultSet {
>
>         @Deprecated
>         @Warning(name="OBSOLETE")
>         InputStream getUnicodeStream(int columnIndex);
>     }
>
> Or on the Collections APIs:
>
>     public interface Collection<E> {
>
>         @Warning(name="OPTIONAL")
>         boolean remove(Object o);
>     }
>
> Or wherever it may seem suitable. The above are just examples.
>
> The advantage of a generic, String-based approach is that @SuppressWarnings
> could be retrofitted to accept any possible @Warning(name):
>
>     Collection<Integer> collection = new ArrayList<>();
>     @SuppressWarnings("OPTIONAL")
>     boolean ok = collection.remove(1);
>
> The same is true for IDEs, which could filter out any such warnings based
> on user settings.
>
> While still addressing the goals mentioned in JEP 277, this would add much
> more substantial value to the whole ecosystem, and to all other library /
> API designers as well.
>
> Curious to hear your feedback,
> Lukas Eder
>