Чи слід використовувати JavaDoc для припинення використання або анотації на Java?

81

На даний момент існує два способи позначити код як застарілий у Java.

Через JavaDoc

/**
 * @deprecated
 */

Або як анотацію:

@Deprecated

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

Однак чи дає використання анотації компілятору фактичну корисну додаткову інформацію?

Але лише використовуючи анотацію, я не можу сказати, чому метод застарілий - я можу робити це лише за допомогою JavaDoc і припиняючи метод, не вказуючи, чому це погано.

Отже, чи можу я використовувати лише один із них? Або я повинен просто навчитися вказувати обидва?

— корграт
джерело

4

Що робити, якщо інший програміст не має ваших джерел? Він не знатиме, що ваш метод застарів. Я б сказав використати анотацію @Deprecated

— Едуард

1

@ t-edd: якщо інший програміст не має ні джерел, ні javadocs (який також відображає анотації), випадкове використання застарілих API є найменшою з цих проблем.

— Michael Borgwardt

1

@ Майкл Борґвардт. Я просто намагався детально розказати, які проблеми це може спричинити. І це лише один, який я міг придумати. Іноді ви можете опустити завантаження джерел та javadoc і використовувати застарілий api, який не буде присутній у наступній версії ...

— Едуард,

76

Ви повинні використовувати обидва. Анотація дозволяє компілятору відображати попередження щоразу, коли використовується застарілий метод, і javadoc пояснює, чому. Обидва важливі.

Згідно з підручником Java Annotations від Oracle :

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

— Rawrgramming
джерело

5

Однак компілятор Oracle також відобразить попередження для тегу javadoc, тому анотація насправді не потрібна.

— Michael Borgwardt

@Michael - у багатьох випадках (але не у всіх, які я собі уявляю), цим можна керувати за допомогою@SuppressWarnings("deprecation")

— luis.espinal

3

@MichaelBorgwardt Я розумію ваше мислення, але занадто багато з цього в кінцевому підсумку призводить до того, що "все одно не пишіть документацію, бо ви можете довіряти лише вихідному коду". Анотація javadoc справді має певну мету, наприклад, це єдине місце, де можна направити користувача "використовувати замість цього заміну".

— Едвін Бак,

3

Амінь Едвін. Той факт, що потрібні 2 позначення, це відмовно.

— ggb667

@MichaelBorgwardt Оскільки JDK 9 javac скаржиться, якщо тег Javadoc використовується без анотації. Має сенс, оскільки інший компілятор може просто перевірити анотацію.

— Мартін

37

З пащі коня :

ПРИМІТКА: Специфікація мови Java вимагає від компіляторів видавати попередження, коли використовуються класи, методи або поля, позначені анотацією @Deprecated. Специфікація мови Java не вимагає від компіляторів видавати попередження під час доступу до класів, методів або полів, позначених тегом @deprecated Javadoc, хоча компілятори Sun в даний час це роблять.

Отже, в основному, якщо ви хочете гарантувати наявність попереджень компілятора, вам потрібно використовувати анотацію. І через дивовижну некомпетентність дизайнера API, вам також потрібно вказати тег javadoc, щоб дати пояснення.

Особисто я б сказав, що анотація марна і її слід опускати, поки вона не буде виправлена, оскільки будь-який хороший компілятор або IDE також відображатиме попередження з тегом javadoc.

— Майкл Боргвардт
джерело

3

"оскільки будь-який хороший компілятор або IDE також відображатиме попередження з тегом javadoc." І будь-який пристойний програміст не буде покладатися на компілятор, щоб розповісти йому про застарілі речі, він буде шукати документацію щодо нових або змінених API.

— jwenting

12

@jwenting, пошук документації - це марна трата людського часу. Зробіть машини зрозуміти, чи не відбувається щось тривожне, і розкажіть про це. Це їх робота.

— thejoshwolfe

2

@jwenting Я не згоден. Анотації та javadocs - це спосіб для програміста "знати" про API. Це діюча форма документації. По можливості програміст повинен використовувати свої сили, щоб думати про цікаві речі, а не шукати документацію, хто знає де.

— Андрес Ф.

3

@jwenting: Гаразд, але як те, що певний API є застарілим, є частиною основ? А як попередження компілятора, що вказують на використання застарілих API в тілі коду, "передбачають наміри програміста"?

— Майкл Борґвардт

8

Я гадаю, найкраще було б, якби анотація @Deprecated могла підтримувати рядок 'value', який міг би прийняти пояснення, чому застаріле місце. Пояснення, здається, єдина причина, по якій хтось би використовував спосіб javadoc замість самої анотації.

— jrharshath

6

Ви повинні написати обидва. Анотація @Deprecated призначена для компілятора, а тег @deprecated JavaDoc - для людини, яка зараз хоче, чому це застаріло.

Приклад може виглядати так:

/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}

— Марсель
джерело

2

Для компілятора? Компілятор не дбає інакше, як лише видавати попередження розробнику, тому вони обидва для розробника. Просто анотація майже марна сама по собі, тоді як коментар javadoc не гарантовано використовуватиметься. Тож Sun / Oracle (я не знаю, на чиєму годиннику це було) створили ситуацію, коли розробники повинні зробити дві різні речі, щоб адекватно задокументувати ситуацію, коли однієї повинно було бути достатньо.

— nasch

Обидві ці відповіді помітні. Ви повинні використовувати обидва, але потрібно лише один.

— thonnor

5

Ви повинні вказати обидва.

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

Це дві дуже різні речі!

— Дунаріл
джерело

6

Це зовсім не різні речі. Якби анотація дозволяла пояснення як параметр, це також могло б відображатися розробникам.

— Michael Borgwardt

@Michael Ваша відповідь наголошує на різниці між ними. Насправді це навіть розвивається за тією ж ідеєю, що і моя.

— Дунаріл

5

ні, у моїй відповіді підкреслюється, що тег javadoc все ще потрібен лише тому, що анотація була розроблена погано. Анотації - це метадані коду та інформація для розробників, як і підписи методів.

— Michael Borgwardt

2

Потребувати 2 тегів - це дурно. Анотація не повинна існувати, оскільки без документації вона майже ні до чого. Насправді зараз я дивуюсь, чому саме ця річ позначена як застаріла. Немає @Deprecated тегу javadoc, тому я поняття не маю. Це відстій. Це майже гірше ніж нічого, тому що хтось колись казав "не використовуй", але не чому. Бажання задушити піднімаючись.

— ggb667

1

З цим легко впоратися за допомогою хорошої IDE.

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

Тому я просто пишу javadoc з відповідним поясненням і дозволяю IDE подбати про додавання анотації @Deprecated, щохвилини, коли я зберігаю файл.

— Невразливий
джерело