Rédaction de documentation pour des méthodes bien comprises comme equals en Java


10

Est-ce une bonne pratique d'écrire des commentaires pour des méthodes largement connues comme equals, compareTo, etc.?

Considérez le code ci-dessous.

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }   

Mon entreprise souhaite entrer des commentaires comme ci-dessus. Le commentaire Javadoc ci-dessus est-il requis? N'est-il pas évident et bien compris ce que fait la méthode des égaux et les goûts (comparer, comparer à), etc.?

Quelles sont vos suggestions?


3
Votre commentaire actuel est incorrect. La signature de votre méthode est correcte pour prendre un objet générique, mais votre commentaire dit «objet du même type».
c_maker

4
Je préfère voir un commentaire expliquant ce que l'égalité signifie pour cet objet. «Égalité» est un terme glissant. Dans Common Lisp, il existe de nombreuses fonctions d'égalité et vous choisissez celle qui convient lors de l'utilisation.
David Thornley

Dans ce cas, je fais référence à deux objets étant égaux de "manière significative". Par exemple, deux objets Employé sont égaux s'ils ont le même ID d'employé, plutôt que de dire qu'ils portent la même chemise de couleur.
Vinoth Kumar CM

6
@Vinoth: la "manière significative" est exactement ce dont vous avez besoin pour documenter :)
c_maker

Réponses:


6

JavaDoc prend déjà en charge l' héritage des commentaires . Selon la documentation, "les constructeurs, les champs et les classes imbriquées n'héritent pas des commentaires doc", mais des méthodes comme equals()will. Étant donné que la Objectclasse a une equals()méthode bien documentée , vous devriez simplement pouvoir hériter de cette documentation sans problème.

La documentation de la méthode doit provenir de quelque part afin qu'elle soit accessible dans votre IDE et dans la documentation Web générée. Il n'est pas nécessaire de réécrire explicitement des commentaires précis et complets qui existent dans une superclasse, et je dirais que les fichiers de code sont encombrés.

S'il s'agit d'une politique d'entreprise, vous avez deux options. Vous pouvez l'accompagner lentement et gérer l'effort supplémentaire d'écriture et de maintenance de la documentation (souvent en violation du principe DRY, qui peut également être appliqué aux documents ainsi qu'au code). L'autre option serait de rechercher la politique de l'entreprise - expliquer pourquoi cette politique n'est pas une bonne idée et les avantages de la changer (en termes de temps, d'argent, d'effort, de qualité - des choses que la direction comprend).


Je suis conscient de l'héritage. Mais la société nous "mandate" pour écrire des documents java explicites.
Vinoth Kumar CM

3
@Vinoth Si c'est la politique de l'entreprise, vous ne pouvez rien faire d'autre que de les écrire ou de chercher à changer la politique. Si vous utilisez des outils de développement modernes, cette stratégie est obsolète. Qu'est-ce qui motive cette politique? Les commentaires JavaDoc sont transformés en pages Web et les IDE modernes vous permettent d'afficher les commentaires JavaDoc lorsque vous écrivez un logiciel, quelle que soit la provenance du commentaire (explicite ou héritée).
Thomas Owens

@Thomas: Il y a le pardon plutôt que de demander l'option de permission: pliez simplement les règles en silence et voyez si quelqu'un se plaint.
dsimcha

@dsimcha Peut-être, mais si cela se répète, cela pourrait être mauvais pour le travail. Ce n'est pas une chose un ou deux.
Thomas Owens

9

Dans mon équipe, nous utilisons généralement l' @inheritDocannotation pour equals()et hashcode()je souhaite que nous ne l'avons pas fait.

Pour ces deux méthodes, je dois toujours regarder la mise en œuvre. Puisque vous remplacez une méthode, cela signifie que vous voulez qu'elle fasse quelque chose de différent. Je pense que cela mérite sa propre documentation.

Il est bon de documenter au moins les attributs qui participent à la méthode et peut-être même pourquoi.


1
Votre dernière déclaration est la meilleure raison de la documenter vous-même. Expliquez ce qu'il fait. Bien sûr, equal () peut comparer tous les éléments de la classe, ou vous pouvez vouloir simplement comparer tous les champs de chaîne, ou autre chose.
Nicholas

2

N'oubliez pas que les commentaires aident les développeurs de toutes sortes s'ils sont corrects.

Le problème est qu'ils sont parfois incomplets et imprécis.

Pour être honnête, la comparaison de 2 objets peut être délicate (par exemple, la comparaison de 2 objets de facture), votre méthode peut également évoluer avec le temps et devra ensuite être commentée.

Montrer l'objectif de la méthode, les règles, etc. dans un commentaire "utile et significatif" est une bonne chose.


2

Il est extrêmement mauvais de jeter du code avec des commentaires vides comme:

/**
 * This method compares the equality of the current object with the object of same type...
 */

Cela ne dit rien d'utile. Pire, il est pauvre en style et en grammaire:

  1. Les commentaires ne doivent jamais commencer par "Cette méthode" ou "Cette classe" ou "Ce" quoi que ce soit. Le commentaire est associé à une méthode ou une classe par son emplacement dans le fichier source.

  2. "l'objet" devrait se lire "un objet"

  3. "Compare l'égalité" n'a de sens que si un objet peut avoir plus "d'égalité" qu'un autre. Cette fonction ne compare pas "l'égalité"; il compare les objets pour déterminer leur égalité les uns avec les autres.

Au lieu de cela, le commentaire doit indiquer quand les deux objets sont considérés comme égaux. Ici, j'omettre complètement la description de la méthode et ne documenter que la valeur de retour, par exemple:

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

Les commentaires générés pour les méthodes get / set triviales sont les pires de tous.


1

Notre norme de codage stipule que lors de la substitution d'une méthode, il n'est pas nécessaire de la documenter, sauf si, en la remplaçant, la documentation dans la classe ou l'interface parent n'est plus précise et complète pour la sous-classe ou la classe d'implémentation.

Pour égal, nous pouvons noter que la comparaison n'est effectuée que sur une clé primaire lors de la comparaison d'une entité soutenue par une base de données car cela n'est pas entièrement cohérent avec la documentation de Object.equals().


0

À mon avis, et je pense que cela peut être controversé, vous devez indiquer dans le commentaire dans quelle classe vous avez remplacé la classe. Ensuite, six mois plus tard, lorsque vous vous demandez s'il est mis en œuvre ou non, vous pourrez voir sans ouvrir la classe.


0

Sachant que ces méthodes sont courantes et que la plupart des développeurs sauront à quoi elles servent alors, OMI, vous n'aurez pas besoin d'y mettre de commentaires. Les commentaires ne sont pas fiables à long terme, car il est possible que ceux-ci ne soient pas mis à jour lors de la mise à jour de l'implémentation et puissent créer de la confusion. Il est donc toujours préférable de rendre votre code lisible car c'est ce à quoi vous pouvez principalement faire confiance.

De plus, je dirais que si le code que vous créez / éditez n'est pas pour une API publique, alors laissez de côté les javadocs pour les méthodes courantes car elles ajouteront simplement de l'encombrement et du bruit.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.