Каков наилучший способ комментировать устаревший класс в Java?

11

Я хотел бы знать, как лучше всего добавить комментарий для идентификации устаревшего класса в Java. Должен ли я удалить предыдущий комментарий, добавленный в начало класса, который помогает другому программисту знать, для чего этот класс, или я должен добавить его под комментарием?

java code-quality api comments alculete
источник

Ответы:

17

Рекомендуемый подход к устареванию класса, метода или поля в Java заключается в использовании @Deprecatedаннотации, ставшей доступной в Java 5, или @deprecatedтега JavaDoc, существующего со времен Java 1.1. У Oracle есть документ об особенностях того, как и когда следует отказываться от API, который представляется уместным.

Должен ли я удалить предыдущий комментарий, добавленный в начало класса, который помогает другому программисту узнать, для чего этот класс, или добавить его под комментарием?

Вы не должны редактировать или удалять любые существующие комментарии, кроме как добавлять тег JavaDoc или аннотацию. Устаревший код может все еще использоваться в устаревших системах, и разработчики этих систем должны иметь доступ к документации, которую первоначальные разработчики сделали в той или иной форме.

Томас Оуэнс
источник
1
+1: Использование аннотаций @Depricated также дает преимущество IDE, таким как Eclipse, чтобы вычеркнуть этот метод и дать другие визуальные подсказки разработчикам.
Райан Хейс
да, я знаю, как осудить и использовать аннотацию отключения мой вопрос, например, у меня есть этот код / ​​** * комментарий о классе ** / public class ClassToDeprecate {// некоторый код здесь}, если я удалю комментарий и буду таким
alculete
1
@Spammer Статья, на которую я ссылался, обсуждает это. Кроме того, просмотр документации по API Java отвечает этому. Единственное, что вам нужно сделать, это добавить @Deprecatedаннотацию или @deprecatedтег JavaDoc. Вот и все - ничего больше, ничего больше.
Томас Оуэнс
кстати, ссылка, которую вы дали, была очень
полезной
1
Добавление @deprecatedтега JavaDoc и описания вместе с @Deprecatedаннотацией даст больше света, почему это устарело. Так что было бы выгоднее использовать оба, а не только @Deprecatedаннотации.
WarFox