É 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?
Respostas:
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 aObject
classe possui umequals()
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).
fonte
Na minha equipe normalmente usamos a
@inheritDoc
anotação paraequals()
ehashcode()
, 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.
fonte
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.
fonte
É uma prática extremamente ruim colocar lixo com comentários vazios, como:
Isso não diz nada de útil. Pior, é ruim no estilo e na gramática:
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.
"o objeto" deve ler "um objeto"
"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:
Comentários gerados para métodos triviais de obtenção / conjunto são os piores de todos.
fonte
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()
.fonte
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.
fonte
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.
fonte