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

10

É 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?

Vinoth Kumar CM
fonte
3
O seu comentário atual está incorreto. Sua assinatura de método está correta ao usar um objeto genérico, mas seu comentário diz 'objeto do mesmo tipo'.
c_maker
4
Prefiro ver um comentário explicando o que igualdade significa para esse objeto. "Igualdade" é um termo escorregadio. No Common Lisp, existem inúmeras funções de igualdade e você escolhe a apropriada em uso.
precisa
Neste caso, estou me referindo a dois objetos sendo iguais de uma "maneira significativa". Por exemplo, dois objetos Employee são iguais se eles tiverem o mesmo ID de funcionário, em vez de dizerem que usam a mesma camisa de cor.
Vinoth Kumar CM
6
@Vinoth: a "forma significativa" é exatamente o que você precisa para um documento :)
c_maker

Respostas:

6

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

Thomas Owens
fonte
Estou ciente de herdar. Mas a empresa "nos manda" escrever documentos java explícitos.
Vinoth Kumar CM
3
@ Vinoth Se essa é a política da empresa, não há nada que você possa fazer além de escrevê-las ou tentar mudar a política. Se você estiver usando ferramentas de desenvolvimento modernas, essa política estará desatualizada. O que impulsiona essa política? Os comentários do JavaDoc são transformados em páginas da Web e os IDEs modernos permitem visualizar os comentários do JavaDoc enquanto você cria um software, independentemente da origem do comentário (explícito ou herdado).
Thomas Owens
@ Thomas: Existe a opção de pedir perdão em vez de pedir permissão: apenas incline as regras em silêncio e veja se alguém reclama.
precisa saber é o seguinte
@dsimcha Talvez, mas se for repetido, isso pode ser ruim para o trabalho. Isso não é uma coisa de um ou dois.
Thomas Owens
9

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.

c_maker
fonte
11
Sua última declaração é a melhor razão para documentá-la. Explique o que está fazendo. Claro que equal () pode comparar todos os elementos da classe, ou você pode comparar apenas todos os campos de string ou qualquer outra coisa.
Nicholas
2

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.

NoChance
fonte
2

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

Kevin Cline
fonte
1

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

Kris
fonte
0

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.

Peter Taylor
fonte
0

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.

Bob Santos
fonte