web-dev-qa-db-fra.com

Dois-je utiliser la dépréciation JavaDoc ou l'annotation en Java?

Il existe actuellement deux façons de marquer le code comme déprécié en Java.

Via JavaDoc

/**
 * @deprecated
 */

Ou en annotation:

@Deprecated

C'est mon problème - je le trouve un peu trop pour déclarer les deux, lors du marquage d'une méthode comme obsolète lors de l'utilisation d'Eclipse. Je veux vraiment utiliser l'un d'eux.

Cependant, l'utilisation de l'annotation donne-t-elle au compilateur des informations supplémentaires utiles?

Mais en utilisant uniquement l'annotation, je ne peux pas expliquer pourquoi la méthode est obsolète - je ne peux le faire qu'avec JavaDoc et déconseiller une méthode sans préciser pourquoi est mauvais.

Alors, puis-je en utiliser un seul? Ou devrais-je vraiment juste apprendre à spécifier les deux?

javaannotationsjavadocdeprecated
74
corgrath

Vous devez utiliser les deux. L'annotation permet au compilateur d'afficher un avertissement chaque fois qu'une méthode obsolète est utilisée, et le javadoc explique pourquoi. Les deux sont importants.

Selon Oracle Java Annotations tutoriel :

Lorsqu'un élément est obsolète, il doit également être documenté à l'aide de la balise Javadoc @deprecated ...

71
Rawrgramming

De la bouche du cheval :

REMARQUE: la spécification de langage Java requiert que les compilateurs émettent des avertissements lorsque des classes, des méthodes ou des champs marqués de l'annotation @Deprecated sont utilisés. Les compilateurs ne sont pas requis par la spécification de langage Java pour émettre des avertissements lorsque des classes, des méthodes ou des champs marqués avec la balise Javadoc @deprecated sont accessibles, bien que les compilateurs Sun le fassent actuellement.

Donc, fondamentalement, si vous voulez une garantie qu'il y aura des avertissements du compilateur, vous devez utiliser l'annotation. Et en raison de l'incompétence à couper le souffle de certains concepteurs d'API, vous devez également spécifier la balise javadoc pour donner une explication.

Personnellement, je dirais que l'annotation est inutile et doit être omise jusqu'à ce qu'elle soit corrigée, car tout bon compilateur ou IDE affichera également des avertissements avec la balise javadoc.

37
Michael Borgwardt

Vous devez spécifier les deux.

L'annotation permet au compilateur de le savoir et de déclencher des avertissements lorsque la méthode est utilisée. L'attribut JavaDoc informe les développeurs avant de commencer à l'utiliser.

Ce sont deux choses très différentes!

5
Dunaril

Vous devez écrire les deux. @Deprecated Anotation est pour le compilateur et la balise @deprecated JavaDoc est pour la personne qui veut maintenant pourquoi cela est déconseillé.

Un exemple peut ressembler à ceci:

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

Cela peut être facilement traité avec un bon IDE.

Eclipse Neon, par exemple. ajoute automatiquement @Deprecated annotation, lorsque je crée un javadoc @deprecated sur une méthode ou un champ.

J'écris donc simplement le javadoc avec l'explication appropriée et je laisse le IDE prendre soin d'ajouter l'annotation @Deprecated, la minute où j'enregistre le fichier.

1
Inxsible