Я иногда сталкивался с ситуацией, в которой мне нужно было представить новый API или конструкцию, чтобы другие могли ее попробовать, но я знал, что она может измениться на основе отзывов других людей после некоторого использования. В таких случаях я хотел как-то аннотировать конструкцию, чтобы предупредить других разработчиков о предварительности этой новой добавленной конструкции. Есть несколько альтернатив, которые я рассмотрел в этих случаях.
- Используйте стороннюю аннотацию, такую как аннотация @Beta от Guava .
- Разработайте собственную аннотацию.
- Используйте комментарии / только Javadoc.
- Используйте аннотацию @Deprecated с тегом Javadoc @deprecated .
Сторонняя аннотация
Документация Javadoc для аннотации @Beta Guava гласит:
Означает, что открытый API (открытый класс, метод или поле) может быть несовместим или изменен в будущем выпуске. API, несущий эту аннотацию, освобождается от любых гарантий совместимости, которые дает содержащая его библиотека. Обратите внимание, что наличие этой аннотации не подразумевает ничего о качестве или производительности рассматриваемого API, только тот факт, что он не «заморожен API».
Это объяснение использования @Beta кажется, подразумевает, что это хорошо подходит для «новой» конструкции, которая может быть удалена. Я больше говорил об этой аннотации в блоге « Две общепринятые аннотации гуавы ».
Другие соображения при использовании аннотации сторонней библиотеки заключаются в том, что сторонняя библиотека должна быть включена в свой путь к классам, и что обычно в самой популярной среде IDE Java отсутствует встроенная поддержка, указывающая на особую обработку конструкции аннотируется с аннотацией.
Пользовательская аннотация
Если вы не используете библиотеку с аннотацией по какой-либо другой причине, может показаться немного сложным добавить новую библиотечную зависимость просто для аннотации, когда относительно просто написать собственную пользовательскую аннотацию. Я уже писал о написании пользовательской аннотации @Unfinished ранее, и в этом посте обсуждалось, как создавать соответствующие пользовательские проверки IDE в NetBeans 8.0.2 и IntelliJ IDEA 14.0.3 для этой пользовательской аннотации.
В следующем листинге кода приведен пример пользовательской аннотации, которую можно использовать для этой цели.
@Preview Аннотация
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
|
package dustin.examples.annotations;import java.lang.annotation.Documented;import java.lang.annotation.ElementType;import java.lang.annotation.Retention;import java.lang.annotation.RetentionPolicy;import java.lang.annotation.Target;@Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.TYPE})@Retention(RetentionPolicy.RUNTIME)@Documentedpublic @interface Preview{ /** * Anticipated release in which Preview status will no longer apply. * * @return Anticipated release of feature */ String transition() default ""; /** * Version in which this preview feature was introduced. * * @return Release in which this preview feature was introduced. */ String since() default ""; /** * Reasons this construct is considered "preview." * * @return Reasons this construct is considered preview. */ String[] reasons() default {};} |
В пользовательской аннотации отсутствует какая-либо готовая поддержка в популярных Java IDE.
Только комментарии
Аннотации не обязательно должны использоваться, и простые комментарии (Javadoc или другие) могут объяснить, что конкретная конструкция является предварительной и может исчезнуть. Тем не менее, комментарии слабее во многих отношениях, чем аннотации с точки зрения передачи намерений. Гораздо сложнее иметь IDE или другие инструменты анализа комментариев, чем обрабатывать аннотации.
@ Устаревшие аннотации и @deprecated Javadoc Tag
Можно использовать @Deprecated чтобы аннотировать устаревшую конструкцию стандартной аннотацией, которую IDE, инструменты и сценарии могут легко обрабатывать. К сожалению, аннотация @Deprecated так и не получила полной поддержки, на которую я надеялся получить более конкретную информацию о том, почему что-то не рекомендуется, когда было решено сделать улучшенный JDK 9 @Deprecated гораздо менее амбициозным. Тег Javadoc @deprecated может использоваться для документирования того, что устаревание фактически относится к «новой» конструкции, которая может исчезнуть, но также может и не исчезнуть. Аннотацию @Deprecated и тег @deprecated Javadoc можно удалить, если будет решено сохранить конструкцию «предварительного просмотра».
Хотя аннотация @Deprecated и тег @deprecated Javadoc пользуются преимуществами стандартов, включающих встроенную поддержку IDE и осведомленность большинства разработчиков Java, все же может показаться немного неуместным использовать их для обозначения новой конструкции, которая может исчезнуть, но может остаться В разделе « Когда следует устаревать » документа « Как и когда отказаться от API » говорится: «При разработке API тщательно продумайте, заменяет ли оно старый API». Кроме того, в нем перечислены три причины устаревания: «небезопасные, с ошибками или крайне неэффективные», «уход в будущем выпуске» и «поощрение плохой практики кодирования».
Я не единственный, кто думает о «устаревании» как о маркировке чего-то, что может быть удалено или не должно использоваться. Николас Френкель обрисовывает в общих чертах жизненный цикл функции в Java и объясняет, что устаревание в Java — это «смелое и ясное заявление для всех, что у версии функции нет будущего, по крайней мере, в ее нынешней форме».
В сообщении списка рассылки jdk-dev « JEP 12: Обработка стандартных API, поддерживающих функции предварительного просмотра », Алекс Бакли пишет:
Мы хотели бы использовать метод устаревания для удаления при рождении в качестве способа пометки «этот API тесно связан с функцией предварительного просмотра». Если функция предварительного просмотра становится постоянной, то устаревание будет удалено. Этот переход от терминального устаревания к отсутствию устаревания является новым, но не безумным — амортизация имеет множество значений, и ее историческое использование в JDK не является хорошим руководством ни к чему.
Бакли также ссылается на абзац из JEP 277 («Устаревший износ»), касающийся использования механизмов амортизации (я выделил ту же часть, которую подчеркнул Бакли):
Устаревание — это метод передачи информации о жизненном цикле API: поощрение перехода приложений от API, отговорка приложений от формирования новых зависимостей от API и информирование разработчиков о рисках сохранения зависимости от API .
«Улучшенная» аннотация @Deprecated представленная в JDK 9, может немного помочь в этой ситуации (которую Бакли назвал «устаревшим для удаления при рождении») благодаря новым добавленным элементам « since » и « forRemoval ». Указание для @Deprecated аннотации forRemoval() как false и указание ее since той же версией, что и тег Javadoc @since, могут помочь разработчикам увидеть, что конструкция устарела с самого начала без текущих планов ее удаления. Чтобы такой подход был наиболее эффективным, он, вероятно, должен был бы записать, чтобы явно указать forRemoval как false, а не полагаться на его неявное значение по умолчанию.
Возможно, мы, разработчики Java, должны начать думать о @Deprecated и @deprecated немного иначе, чем в прошлом. Хотя аннотация @Deprecated и тег @deprecated Javadoc по-прежнему «информируют» нас о «рисках сохранения зависимости» от аннотированной / описанной конструкции, может быть неверным полагать, что такая конструкция обязательно исчезнет в какой-то момент в будущем. , Если мы привыкнем к этому альтернативному значению в устаревших конструкциях JDK, мы с большей вероятностью рассмотрим возможность использования того же подхода с нашими собственными новыми и все еще пробными функциями.
| Опубликовано на Java Code Geeks с разрешения Дастина Маркса, партнера нашей программы JCG . Смотрите оригинальную статью здесь: Взгляд в будущее с @Deprecated Java
Мнения, высказанные участниками Java Code Geeks, являются их собственными. |