É uma prática correta adicionar comentários Javadoc na interface e adicionar comentários não Javadoc na implementação?
A maioria dos IDEs gera comentários não JavaDoc para implementações quando você gera comentários automaticamente. O método concreto não deveria ter a descrição?
Respostas:
Para métodos que são apenas implementação (não substituições), claro, por que não, especialmente se eles forem públicos.
Se você tiver uma situação de substituição e for replicar qualquer texto, definitivamente não o fará. A replicação é uma maneira infalível de causar discrepâncias. Como resultado, os usuários teriam uma compreensão diferente do seu método com base no fato de examinarem o método no supertipo ou no subtipo. Use @inheritDocou não forneça uma documentação - Os IDEs usarão o menor texto disponível para usar em sua visualização Javadoc.
Como um aparte, se a sua versão sobrescrita adiciona coisas à documentação do supertipo, você pode estar em um mundo de problemas. Estudei esse problema durante meu PhD e descobri que, em geral, as pessoas nunca estarão cientes das informações extras na versão de substituição se estiverem invocando por meio de um supertipo.
Abordar esse problema foi um dos principais recursos da ferramenta de protótipo que eu construí - sempre que você invocava um método, recebia uma indicação se seu destino ou qualquer destino de substituição potencial continha informações importantes (por exemplo, um comportamento conflitante). Por exemplo, ao invocar put on a map, você foi lembrado de que, se sua implementação for um TreeMap, seus elementos precisam ser comparáveis.
Tanto a implementação quanto a interface devem ter javadoc. Com algumas ferramentas, você pode herdar a documentação da interface com a palavra-chave @inheritDoc.
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }{@inheritDoc}e só funciona se você não tiver a anotação @Overrideprimeiro
Uma boa prática é colocar
/**
* {@inheritDoc}
*/como javadoc da implementação (a menos que haja algo extra a ser explicado sobre os detalhes da implementação).
Geralmente, ao substituir um método, você adere ao contrato definido na classe / interface base, portanto, não deseja alterar o javadoc original de qualquer maneira. Portanto, o uso da tag @inheritDocou @seemencionado em outras respostas não é necessário e, na verdade, apenas serve como um ruído no código. Todas as ferramentas sensíveis herdam o método javadoc da superclasse ou interface conforme especificado aqui :
Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:
- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interfaceO fato de algumas ferramentas (estou olhando para você, Eclipse!) Gerarem isso por padrão ao substituir um método é apenas um triste estado de coisas, mas não justifica confundir seu código com ruídos inúteis.
É claro que pode haver o caso oposto, quando você realmente deseja adicionar um comentário ao método de substituição (geralmente alguns detalhes adicionais de implementação ou tornar o contrato um pouco mais rígido). Mas, neste caso, você quase nunca quer fazer algo assim:
/**
* {@inheritDoc}
*
* This implementation is very, very slow when b equals 3.
*/Por quê? Porque o comentário herdado pode ser muito longo. Nesse caso, quem vai notar a frase extra no final dos 3 parágrafos longos ?? Em vez disso, apenas escreva o seu próprio comentário e pronto. Todas as ferramentas javadoc sempre mostram algum tipo de link Especificado por, no qual você pode clicar para ler o comentário da classe base. Não faz sentido misturá-los.
@see Gera um link para a descrição na interface. Mas acho bom acrescentar alguns detalhes sobre a implementação também.
@seemétodos de link para interface é uma boa prática e é suficiente na maioria dos casos. Quando você copia o javadoc do método de interface para a implementação concreta, você apenas duplica as informações e elas podem rapidamente se tornar inconsistentes. No entanto, qualquer informação adicional sobre a implementação deve ser adicionada ao javadoc.
Sjoerd diz corretamente que tanto a interface quanto a implementação devem ter JavaDoc. A interface JavaDoc deve definir o contrato do método - o que o método deve fazer, quais entradas ele recebe, quais valores ele deve retornar e o que deve fazer em caso de erro.
A documentação de implementação deve observar extensões ou restrições no contrato, e também detalhes apropriados da implementação, especialmente desempenho.
Por causa do javadoc gerado, sim, isso importa. Se você declarar referências a uma implementação concreta usando apenas a interface, isso não acontecerá, pois os métodos da interface serão recuperados pelo IDE.