Jaki jest najlepszy sposób skomentowania przestarzałej klasy w Javie?

11

Chciałbym poznać najlepszy sposób dodania komentarza w celu zidentyfikowania przestarzałej klasy w Javie. Czy powinienem usunąć poprzedni komentarz dodany na początku klasy, który pomaga innemu programistowi dowiedzieć się, do czego służy ta klasa, czy powinienem dodać go pod komentarzem?

java code-quality api comments alculete
źródło

Odpowiedzi:

17

Zalecanym podejściem do zastępowania klasy, metody lub pola w Javie jest użycie @Deprecatedadnotacji, która stała się dostępna w Javie 5, lub @deprecatedznacznika JavaDoc, który istnieje już od Java 1.1. Oracle ma dokument na temat szczegółów, w jaki sposób i kiedy należy wycofywać interfejsy API, które wydają się istotne.

Czy powinienem usunąć poprzedni komentarz dodany na początku klasy, który pomaga innemu programistowi dowiedzieć się, do czego była ta klasa, czy dodać go pod komentarzem?

Nie należy edytować ani usuwać żadnych istniejących komentarzy poza dodaniem znacznika JavaDoc lub adnotacji. Przestarzały kod może być nadal używany w starszych systemach, a programiści tych systemów muszą mieć dostęp do dokumentacji, którą zrobili pierwotni programiści w jakiejś formie.

Thomas Owens
źródło
1
+1: Korzystanie z adnotacji @Depricated daje również głowy IDE, takim jak Eclipse, aby upewnić się, że wykreślono tę metodę i dano deweloperom inne wskazówki wizualne.
Ryan Hayes,
tak, wiem, jak wycofać i użyć adnotacji moje pytanie to na przykład mam ten kod / ** * komentarz na temat klasy ** / public class ClassToDeprecate {// jakiś kod tutaj} powinienem usunąć komentarz i być taki
alculete
1
@Spamer W artykule, który podlinkowałem, omawiam to. Również przeglądanie dokumentacji interfejsu API Java odpowiada na to. Jedyne, co powinieneś zrobić, to dodać @Deprecatedadnotację lub @deprecatedznacznik JavaDoc. To wszystko - nic więcej, nic więcej.
Thomas Owens
przy okazji, link, który podałeś był bardzo pomocny
alculete
1
Dodanie @deprecatedznacznika i opisu JavaDoc wraz z @Deprecatedadnotacją pozwoli lepiej zrozumieć, dlaczego zostało ono przestarzałe. Bardziej korzystne byłoby użycie obu niż tylko @Deprecatedadnotacji.
WarFox,