Escrevendo documentação para métodos bem entendidos, como iguais em Java

É uma boa prática escrever comentários para métodos amplamente conhecidos como iguais, compareTo etc?

Considere o código abaixo.

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

               //code for equals

     }   

Minha empresa deseja inserir comentários como o descrito acima. O comentário Javadoc acima é necessário? Não é óbvio e bem entendido o que o método equals e os gostos (compare, compareTo) etc fazem?

Quais são as suas sugestões?

O JavaDoc já suporta a herança de comentários . De acordo com a documentação, "construtores, campos e classes aninhadas não herdam comentários de documentos", mas métodos como o equals()serão. Como a Objectclasse possui um equals()método bem documentado , você deve poder herdar essa documentação sem problemas.

A documentação para o método precisa vir de algum lugar para que seja acessível no seu IDE e na documentação da web gerada. Reescrever explicitamente comentários precisos e abrangentes que existem em uma superclasse não é necessário, e eu argumentaria desorganizar os arquivos de código.

Se essa é uma política corporativa, você tem duas opções. Você pode acompanhá-lo com moderação e lidar com o esforço extra de escrever e manter a documentação (muitas vezes violando o princípio DRY, que também pode ser aplicado aos documentos e ao código). A outra opção seria buscar a política da empresa - explicar por que essa política não é uma boa ideia e os benefícios de alterá-la (em termos de tempo, dinheiro, esforço, qualidade - coisas que a gerência entende).

Na minha equipe normalmente usamos a @inheritDocanotação para equals()e hashcode(), mas eu gostaria que não o fez.

Para esses dois métodos, sempre tenho que olhar para a implementação. Como você está substituindo um método, isso significa que você deseja fazer algo diferente. Eu acho que isso merece sua própria documentação.

É bom documentar pelo menos quais atributos participam do método e até mesmo por que motivo.

Lembre-se de que os comentários ajudam os desenvolvedores de todos os tipos, se estiverem corretos.

O problema é que eles às vezes são incompletos e não são precisos.

Para ser honesto, comparar 2 objetos pode ser complicado (por exemplo, comparar 2 objetos de fatura), também seu método pode evoluir com o tempo e, então, precisa ser comentado.

Mostrar o objetivo do método, regras, etc. em um comentário "útil e significativo" é uma coisa boa.

É uma prática extremamente ruim colocar lixo com comentários vazios, como:

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

Isso não diz nada de útil. Pior, é ruim no estilo e na gramática:

1. Os comentários nunca devem começar com "Este método" ou "Esta classe" ou "Este" qualquer coisa. O comentário está associado a um método ou classe por sua localização no arquivo de origem.

2. "o objeto" deve ler "um objeto"

3. "Compara a igualdade" só faz sentido se um objeto puder ter mais "igualdade" que outro. Esta função não compara "igualdade"; ele compara objetos para determinar sua igualdade um com o outro.

Em vez disso, o comentário deve indicar quando os dois objetos são considerados iguais. Aqui, eu omitiria completamente a descrição do método e documentaria apenas o valor de retorno, por exemplo:

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

Comentários gerados para métodos triviais de obtenção / conjunto são os piores de todos.

Nosso padrão de codificação determina que, ao substituir um método, não é necessário documentá-lo, a menos que, ao substituí-lo, a documentação na classe ou interface pai não seja mais precisa e abrangente para a sub ou classe de implementação.

Para iguais, podemos observar que a comparação é feita apenas em uma chave primária ao comparar uma entidade suportada por banco de dados, pois isso não é totalmente consistente com a documentação para Object.equals().

Na minha opinião, e acho que isso pode ser controverso, você deve indicar no comentário em qual classe você substituiu a classe. Depois, seis meses depois, quando você se perguntar se foi implementado ou não, poderá ver sem abrir a turma.

Sabendo que esses métodos são comuns e a maioria dos desenvolvedores saberá para que servem, IMO, você não precisará colocar nenhum comentário. Os comentários não são tão confiáveis ​​a longo prazo, pois há chances de que eles não sejam atualizados quando a implementação é atualizada e podem causar confusão. Portanto, é sempre melhor tornar seu código legível, pois é nisso que você pode confiar mais.

Além disso, eu diria que, se o código que você está criando / editando não for para uma API pública, deixe de fora os javadocs para métodos comuns, pois eles apenas adicionarão confusão e ruído.