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

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?

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).

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.

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.

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.

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().

À 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.

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.