Должен ли я использовать устаревший JavaDoc или аннотации в Java? - PullRequest
Новая
       43

Должен ли я использовать устаревший JavaDoc или аннотации в Java?

74 голосов
/ 18 февраля 2011

На данный момент существует два способа пометить код как отключенный в java.

Через JavaDoc 

/**
 * @deprecated
 */

Или как аннотацию: 

@Deprecated

Это моя проблема - я считаю, что объявлять метод как устаревший при использовании Eclipse слишком сложно.Я действительно просто хочу использовать один из них.

Но дает ли использование аннотации действительно полезную дополнительную информацию компилятору?

Но только используя аннотацию, я не могу сказать, почему метод устарел -Я могу сделать это только с помощью JavaDoc и осуждаю метод, не уточняя, почему это плохо.

Итак, я могу использовать только один из них?Или я должен просто научиться определять оба?

Ответы [ 5 ]

71 голосов
/ 18 февраля 2011

Вы должны использовать оба.Аннотация позволяет компилятору отображать предупреждение всякий раз, когда используется устаревший метод, и Javadoc объясняет, почему.Оба важны.

В соответствии с аннотациями Java Oracle учебное пособие :

Когда элемент устарел, его также следует задокументировать с помощью тега Javadoc @deprecated...

37 голосов
/ 18 февраля 2011

Изо рта :

ПРИМЕЧАНИЕ. Спецификация языка Java требует, чтобы компиляторы выдавали предупреждения при использовании классов, методов или полей, помеченных аннотацией @Deprecated.В Спецификации языка Java не требуется, чтобы компиляторы выдавали предупреждения при обращении к классам, методам или полям, помеченным тегом @deprecated Javadoc, хотя в настоящее время компиляторы Sun делают это.вам нужна гарантия, что будут предупреждения компилятора, вам нужно использовать аннотацию.А из-за потрясающей некомпетентности какого-то дизайнера API вам также нужно указать тег javadoc, чтобы дать объяснение.

Лично я бы сказал, что аннотация бесполезна и должна быть опущена до тех пор, пока она не будет исправленаКомпилятор или IDE также будут отображать предупреждения с тегом javadoc.

5 голосов
/ 31 марта 2015

Вы должны написать оба.@Deprecated Anotation предназначен для компилятора, а тег @deprecated JavaDoc предназначен для лица, которое хочет узнать, почему это устарело.

Пример может выглядеть следующим образом: 

/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}
5 голосов
/ 18 февраля 2011

Вы должны указать оба.

Аннотация позволяет компилятору знать об этом и инициировать предупреждения при использовании метода.Атрибут JavaDoc позволяет разработчикам узнать, прежде чем они начнут его использовать.

Это две совершенно разные вещи!

1 голос
/ 21 октября 2016

Это можно легко решить с помощью хорошей IDE.

Eclipse Neon, например.автоматически добавляет аннотацию @Deprecated, когда я создаю javadoc @deprecated для метода или поля.

Поэтому я просто пишу javadoc с соответствующим объяснением и позволяю IDE позаботиться о добавлении аннотации @Deprecated, минутаЯ сохраняю файл.

...