Шаг 1: объявить об удалении
Можно подумать, что отказ от API означает объявление о его удалении, но это не единственный вариант использования (как описано в соответствующих статьях, например, Java 7 и Java 9 ):
API опасен (например, метод Thread.stop).
Существует простое переименование (например, AWT Component.show/hide заменено на setVisible).
Вместо этого можно использовать более новый и лучший API.
Устаревший API будет удален.
Чтобы еще больше усложнить ситуацию, до Java 9 ни один устаревший API в JDK никогда не удалялся (см. 20 лет устаревания Java ), поэтому понятно, что разработчики не воспринимают устаревание серьезно - ни в JDK, ни где-либо еще.
Следовательно, вам необходимо четко сообщить, что API действительно, действительно будет удален . Способ сделать это зависит от версии Java, с которой скомпилирован ваш API.
Java 8 или ниже
В этих версиях Java не существует формального способа явного различения различных вариантов использования устаревших. Лучшее, что вы можете сделать, это добавить тег Javadoc @deprecated, не только указав причину устаревания и перечислив альтернативы, но и явно объявив о своем намерении удалить API.
Java 9 или выше
Начиная с Java 9, с Enhanced Deprecation , теперь вы можете писать
@Deprecated(forRemoval=<boolean>)
для явного документирования вашего намерения. Я думаю, что вместе с Javadoc @deprecated (который должен детализировать причину устаревания и перечислить альтернативы), этот стандартизированный флаг является справедливым предупреждением.
Если для этого флага установлено значение true, компилятор будет предупреждать о каждом использовании устаревшего элемента, например:
YourClass.java:<line>: warning: [removal] <method> in <class> has been
deprecated and marked for removal
Это предупреждение включено по умолчанию (вместо того, чтобы включать его с помощью -Xlint:deprecation) и не подавляется с помощью @SuppressWarnings("deprecation"). Вместо этого нужно было бы подавить его с помощью нового @SuppressWarnings("removal"), что может заставить разработчиков дважды подумать об этом без действительно веской причины.
Кроме того, вы можете явно указать версию библиотеки, которая ввела устаревание, с помощью
@Deprecated(since="<version>")
Просмотр этого в Javadoc или источниках может помочь разработчикам оценить, насколько срочно необходимо обновить их код.
Шаг 2a: предупреждение во время выполнения
Если это возможно для ситуации, добавьте напоминание времени выполнения: когда устаревший API используется, он должен записать предупреждение в консоль или файл журнала (используя любой используемый механизм ведения журнала), объявляя, что это больше не будет работать со следующей основной выпуск. Чтобы избежать спама, вы можете войти в систему только один раз (например, private static boolean warningLogged).
Шаг 2b: Статический анализ кода
Статические анализаторы кода, такие как SonarQube (также доступны как размещенная служба ), могут быть настроены для пометки каждого из этих предупреждений. Правило SonarQube «не рекомендуется использовать устаревший код» должно работать, даже если предупреждение об использовании устаревшего компилятора подавлено.
SonarQube также отслеживает, когда возникла определенная проблема (то есть нарушение правила) (на основе контроля версий), и вы можете в интерактивном режиме фильтровать списки его проблем на основе этой даты. Например, вы могли бы перечислить все случаи использования устаревшего кода, который был в вашей кодовой базе более года, чтобы вы могли расставить приоритеты в работе по их исправлению.
Шаг 3: Удалить API
Фактическое удаление API не даст вашим пользователям API впечатление, что им не нужно беспокоиться об изменении своего кода.