Escribir documentación para métodos bien entendidos como iguales en Java

¿Es una buena práctica escribir comentarios para métodos ampliamente conocidos como equals, compareTo, etc.?

Considere el siguiente código.

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

               //code for equals

     }   

Mi empresa se obliga a ingresar comentarios como los anteriores. ¿Se requiere el comentario Javadoc anterior? ¿No es obvio y bien entendido lo que hace el método de igualdad y los gustos (compare, compareTo), etc.

Cuales son tus sugerencias?

JavaDoc ya admite la herencia de comentarios . Según la documentación, "los constructores, los campos y las clases anidadas no heredan los comentarios del documento", sino métodos como equals()will. Como la Objectclase tiene un equals()método bien documentado , debería poder heredar esa documentación sin ningún problema.

La documentación para el método debe provenir de algún lugar para que sea accesible en su IDE y en la documentación web generada. No es necesario reescribir explícitamente los comentarios precisos y completos que existen en una superclase, y diría que desordenan los archivos de código.

Si esta es una política corporativa, entonces tiene dos opciones. Puede aceptarlo con lentitud y lidiar con el esfuerzo adicional de escribir y mantener la documentación (a menudo en violación del principio DRY, que también se puede aplicar a los documentos y al código). La otra opción sería buscar la política de la empresa: explique por qué esta política no es una buena idea y los beneficios de cambiarla (en términos de tiempo, dinero, esfuerzo, calidad, cosas que la gerencia entiende).

En mi equipo usualmente usamos la @inheritDocanotación para equals()y hashcode()pero desearía que no lo hiciéramos.

Para estos dos métodos, siempre tengo que mirar la implementación. Como está anulando un método, eso significa que quiere que haga algo diferente. Creo que esto merece su propia documentación.

Es bueno al menos documentar qué atributos participan en el método e incluso tal vez por qué es así.

Recuerde que los comentarios ayudan a los desarrolladores de todo tipo si son correctos.

El problema es que a veces están incompletos y no son precisos.

Para ser honesto, comparar 2 objetos puede ser complicado (por ejemplo, comparar 2 objetos de factura), también su método puede evolucionar con el tiempo y luego necesitaría ser comentado.

Mostrar el objetivo del método, las reglas, etc. en un comentario "útil y significativo" es algo bueno.

Es una práctica extremadamente pobre arrojar código con comentarios vacíos como:

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

Esto no dice nada útil. Peor aún, es pobre tanto en estilo como en gramática:

1. Los comentarios nunca deben comenzar con "Este método" o "Esta clase" o "Esto" nada. El comentario está asociado con un método o clase por su ubicación en el archivo fuente.

2. "el objeto" debería leer "un objeto"

3. "Compara la igualdad" solo tiene sentido si un objeto puede tener más "igualdad" que otro. Esta función no compara "igualdad"; compara objetos para determinar su igualdad entre sí.

En cambio, el comentario debe indicar cuándo los dos objetos se consideran iguales. Aquí, omitiría la descripción del método por completo, y solo documentaría el valor de retorno, por ejemplo:

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;
  }
...
}

Los comentarios generados para métodos triviales get / set son los peores de todos.

Nuestro estándar de codificación dicta que al anular un método no es necesario documentarlo a menos que, al anularlo, la documentación en la clase o interfaz principal ya no sea precisa y completa para la subclase o la clase de implementación.

Para iguales, podríamos tener en cuenta que la comparación solo se realiza en una clave principal cuando se compara una entidad respaldada por una base de datos, ya que no es del todo coherente con la documentación para Object.equals().

En mi opinión, y creo que esto puede ser controvertido, debe indicar en el comentario en qué clase ha anulado la clase. Luego, seis meses después, cuando se pregunte si está implementado o no, podrá ver sin abrir la clase.

Sabiendo que esos métodos son comunes y la mayoría de los desarrolladores sabrán para qué sirven, en mi opinión, no necesitará poner ningún comentario allí. Los comentarios no son tan confiables a largo plazo, ya que hay posibilidades de que estos no se actualicen cuando se actualiza la implementación y puedan causar confusión. Por lo tanto, siempre es mejor hacer que su código sea legible, ya que esto es en lo que puede confiar principalmente.

Además, diría que si el código que está creando / editando no es para una API pública, simplemente omita los javadocs para los métodos comunes, ya que estos solo agregarán desorden y ruido.