Quelle est la meilleure façon de commenter une classe obsolète en Java?

11

Je voudrais connaître la meilleure façon d'ajouter un commentaire pour identifier une classe obsolète en Java. Dois-je supprimer le commentaire précédent ajouté en haut de la classe qui aide un autre programmeur à savoir à quoi servait cette classe, ou dois-je l'ajouter sous le commentaire?

java code-quality api comments alculete
la source

Réponses:

17

L'approche recommandée pour déprécier une classe, une méthode ou un champ en Java consiste à utiliser l' @Deprecatedannotation, qui est devenue disponible dans Java 5, ou la @deprecatedbalise JavaDoc, qui existe depuis Java 1.1. Oracle a un document sur les détails sur la façon et le moment de déprécier les API qui semblent pertinents.

Dois-je supprimer le commentaire précédent ajouté en haut de la classe qui aide un autre programmeur à savoir à quoi servait cette classe ou l'ajouter en dessous du commentaire?

Vous ne devez pas modifier ou supprimer des commentaires existants, sauf pour ajouter la balise ou l'annotation JavaDoc. Le code obsolète peut toujours être utilisé dans les systèmes hérités, et les développeurs de ces systèmes doivent avoir accès à la documentation que les développeurs d'origine ont faite sous une forme ou une autre.

Thomas Owens
la source
1
+1: L'utilisation des annotations @Depricated donne également un avertissement aux IDE comme Eclipse pour s'assurer de rayer cette méthode et de donner d'autres conseils visuels aux développeurs.
Ryan Hayes
oui je sais comment déprécier et utiliser l'annotation off ma question est par exemple j'ai ce code / ** * commentaire sur la classe ** / classe publique ClassToDeprecate {// un peu de code ici} devrais-je supprimer le commentaire et être comme ça
alculete
1
@Spammer L'article auquel j'ai lié en parle. En outre, la navigation dans la documentation de l'API Java répond à cela. La seule chose que vous devez faire est d'ajouter l' @Deprecatedannotation ou la @deprecatedbalise JavaDoc. C'est tout - rien d'autre, rien de plus.
Thomas Owens
au fait, le lien que vous avez donné était très utile
alculete
1
Ajouter une @deprecatedbalise et une description JavaDoc avec une @Deprecatedannotation donnera plus de lumière sur la raison pour laquelle elle a été déconseillée. Il serait donc plus avantageux d'utiliser les deux plutôt que de simplement @Deprecatedannoter.
WarFox