Qual é a melhor maneira de comentar uma classe reprovada em Java?

11

Gostaria de saber a melhor maneira de adicionar um comentário para identificar uma classe reprovada em Java. Devo remover o comentário anterior adicionado à parte superior da classe que ajuda outro programador a saber para que serve essa classe ou devo adicioná-lo abaixo do comentário?

java code-quality api comments alculete
fonte

Respostas:

17

A abordagem recomendada para descontinuar uma classe, método ou campo em Java é usar a @Deprecatedanotação, que ficou disponível no Java 5, ou a @deprecatedtag JavaDoc, que existe desde o Java 1.1. A Oracle possui um documento sobre os detalhes específicos de como e quando descontinuar APIs que parecem relevantes.

Devo remover o comentário anterior adicionado à parte superior da classe que ajuda outro programador a saber para que era essa classe ou adicioná-la abaixo do comentário?

Você não deve editar ou remover nenhum comentário existente, exceto adicionar a tag ou anotação JavaDoc. O código descontinuado ainda pode estar em uso em sistemas legados, e os desenvolvedores desses sistemas precisam ter acesso à documentação que os desenvolvedores originais fizeram de alguma forma.

Thomas Owens
fonte
1
+1: o uso das anotações @ Depricated também informa os IDEs como o Eclipse, para garantir que você cruze esse método e dê outras dicas visuais aos desenvolvedores.
Ryan Hayes
sim, eu sei como descontinuar e usar a anotação. Minha pergunta é, por exemplo, eu tenho este código / ** * comentário sobre a classe ** / public class ClassToDeprecate {// algum código aqui} devo remover o comentário e ficar assim
alculete
1
@ Spammer O artigo ao qual vinculei discute isso. Além disso, a navegação na documentação da API Java responde a isso. A única coisa que você deve fazer é adicionar a @Deprecatedanotação ou a @deprecatedtag JavaDoc. É isso - nada mais, nada mais.
Thomas Owens
a propósito, o link que você deu foi muito útil
alculete 13/09/11
1
A adição da @deprecatedtag e descrição do JavaDoc, juntamente com a @Deprecatedanotação, fornecerá mais informações sobre por que ela foi descontinuada. Portanto, seria mais benéfico usar os dois do que apenas a @Deprecatedanotação.
WarFox