web-dev-qa-db-fra.com

Javadoc @return tag duplication de commentaire nécessaire?

Pour les fonctions qui ne modifient pas l'état d'une instance, le commentaire javadoc de la méthode est souvent identique ou très similaire à celui de la @ return-tag dans l'API Java.

booléen Collection.isEmpty ()

  • Renvoie true si cette collection ne contient aucun élément.
  • Renvoie: true si cette collection ne contient aucun élément

Maintenant, j'écris javadoc pour de nombreuses méthodes simples comme getExpression () où j'ai le même problème. Dois-je le faire comme dans l'API ou le laisser de côté?

javajavadoc
31
Konrad Höffner

D'après la recommandation d'Oracle Comment écrire des commentaires de document pour l'outil Javadoc :

@return (page de référence)

Omettez @return pour les méthodes qui renvoient void et pour les constructeurs; l'inclure pour toutes les autres méthodes, même si son contenu est entièrement redondant avec la description de la méthode . Le fait d'avoir une balise @return explicite permet à quelqu'un de trouver plus rapidement la valeur de retour. Dans la mesure du possible, fournissez des valeurs de retour pour des cas spéciaux (par exemple, en spécifiant la valeur renvoyée lorsqu'un argument hors limites est fourni).

20
Alex Stybaev

Si vous (comme moi) n'aimez vraiment pas violer DRY, alors c'est l'une des lignes les plus importantes de la référence javadoc:

Il est possible d'avoir un commentaire avec seulement une section de balise et sans description principale.

(@see http://docs.Oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#tagsection )

Il est donc parfaitement valide (et fonctionnel) pour des méthodes simples d'écrire votre javadoc comme:

/**
* @return the name of the object
*/
public String getName();

Vous pouvez donc même écrire quelque chose comme ceci:

/**
* @return the n-th element of the object
*
* @param n index of element to get
*/
public String get( int n );

Ce qui est (après un peu de connaissance) plus lisible en source et mieux maintenable que la forme plus longue qui viole DRY.

21
Scheintod