Comente a interface, implementação ou ambos?

Eu imagino que todos nós (quando podemos ser incomodados!) Comentamos nossas interfaces. por exemplo

///  /// Foo Interface ///  public interface Foo { ///  /// Will 'bar' ///  /// Wibble factor void Bar(string wibble); } 

Você também comenta a implementação (que também pode ser fornecida aos clientes, por exemplo, como parte da biblioteca aa)? Se sim, como você gerencia mantendo os dois em sincronia? Ou você acabou de adicionar um comentário “Ver interface para documentação”?

obrigado

Como regra geral, eu uso o mesmo princípio DRY (Don’t Repeat Yourself) como no código:

  • na interface, documente a interface
  • na implementação, documente os detalhes da implementação

Java específico : ao documentar a implementação, use a tag {@inheritDoc} para “include” javadocs na interface.

Para maiores informações:

  • Documentação oficial do javadoc
  • Algum conselho não oficial.

Se você usar o suplemento do GhostDoc , ele atualizará a implementação com o comentário da interface quando você clicar com o botão direito do mouse e selecionar “Document This” no método.

Para c # depende IMO: se você usar implementações de interface explícitas, não documentaria a implementação.

No entanto, se você implementar a interface diretamente e expor os membros da interface com o object, esses methods também deverão ser documentados.

Como Nath disse, você pode usar o GhostDoc para inserir automaticamente a documentação de uma interface na implementação. Eu mapeei o comando Document This para o atalho Ctrl + Shift + D e é um dos pressionamentos de teclas que quase automaticamente pressiono. Eu acredito que o ReSharper também tem a opção de inserir a documentação da interface, quando implementa os methods para você.

Nós apenas comentamos a interface, os comentários são tão fáceis de sair de sincronia com a class / interface derivada ou base que é bom tê-la em um só lugar.

Embora pareça que o @Nath talvez esteja sugerindo uma ferramenta de documentação automatizada que ajuda a manter as coisas juntas (parece legal se você usar isso). Aqui em WhereIWorkAndYouDontCare os comentários são para dev para que um único lugar no código seja preferido

Apenas a interface. Comentar ambos é duplicado e é provável que os dois conjuntos de comentários acabem saindo de sincronia se o código mudar. Comente a implementação com “implementa MyInterface” … Coisas como o Doxygen gerarão documentos que incluam os documentos derivados nos documentos para a implementação de qualquer maneira (se você configurá-los corretamente).

Comentando a interface deve haver documentação suficiente para descobrir como usar a implementação real. A única vez que adicionaria comentários à implementação seria se ela tivesse funções particulares inseridas para satisfazer a interface, no entanto, elas seriam apenas comentários internos e não seriam vistas na documentação on-line ou disponíveis para os clientes.

As implementações são apenas isso, desde que estejam em conformidade com a interface, não há necessidade de documentá-las separadamente.

Eu criei uma ferramenta que pós-processa os arquivos de documentação XML para adicionar suporte para a tag .

Embora não auxilie no Intellisense no código-fonte, ele permite que os arquivos de documentação XML modificados sejam incluídos em um pacote NuGet e, portanto, funciona com o Intellisense nos pacotes NuGet referenciados.

Está em http://www.inheritdoc.io (versão gratuita disponível).