Comentar a interface, implementação ou ambos?


128

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

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
    /// <summary>
    /// Will 'bar'
    /// </summary>
    /// <param name="wibble">Wibble factor</param>
    void Bar(string wibble);
}

Você também comenta a implementação (que também pode ser fornecida aos clientes, por exemplo, como parte de uma biblioteca)? Se sim, como você consegue manter os dois sincronizados? Ou você acabou de adicionar um comentário 'Ver interface para documentação'?

obrigado


Uma duplicata esgueirou-se por aqui: stackoverflow.com/questions/1875440/…
bytedev

Respostas:


98

Como regra geral, eu uso o mesmo princípio DRY (não se repita) como no código:

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

Específico para Java : ao documentar a implementação, use a tag {@inheritDoc} para "incluir" javadocs na interface.

Para maiores informações:


Frescos obrigado pela informação que eu não sabia sobre a tag @inheritDoc
Paul Whelan

Uau ... eu também não tinha ideia {@inheritDoc}! Vou usá-lo regularmente a partir de hoje.
Mcherm

35
Para C #, você pode usar <inheritdoc />, suportado pelo SandCastle. ( Mais informações ... )
Daniel AA Pelsmaeker 08/07/12

2
Propriedades e outros elementos em uma classe herdada não mostram a documentação XML na dica de ferramenta quando especificada apenas na interface. Para uso externo da mesma classe, é visível. Isso pode ser um bug com o Visual Studio 2015.
SondreB

2
Aqui está uma versão atualizada do link @Virtlink fornecido para a inheritdocpágina Sandcastle / SHFB : ewsoftware.github.io/XMLCommentsGuide/html/…
weir

7

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


5

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

No entanto, se você implementar a interface diretamente e expor os membros da interface com seu objeto, esses métodos 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. Mapeei o documento Este comando para o atalho Ctrl + Shift + D e é uma das teclas pressionadas quase automaticamente. Acredito que o ReSharper também tenha a opção de inserir a documentação da interface, quando implementar os métodos para você.


4

Apenas a interface. Comentar ambos é duplicação e é provável que os dois conjuntos de comentários acabem ficando fora de sincronia se o código for alterado. Comente a implementação com "implementa MyInterface" ... Coisas como Doxygen irão gerar documentos que incluem os documentos derivados nos documentos para a implementação de qualquer maneira (se você os configurar corretamente).


4

Nós apenas comentamos a interface, é tão fácil ficar fora de sincronia com a classe / interface derivada ou com base, que é bom tê-la em apenas um lugar.

Embora pareça @Nath, talvez sugira uma ferramenta de documentação automatizada que ajude a manter as coisas juntas (parece legal se você a usar). Aqui em WhereIWorkAndYouDontCare, os comentários são para dev, portanto, um único local no código é preferido


Não automatizado, requer ação do usuário, infelizmente.
NikolaiDante 17/04/09

3

Comentar a interface deve ser documentação suficiente para descobrir como usar a implementação real. A única vez em que eu adicionaria comentários à implementação é se ela tivesse funções particulares que foram inseridas para satisfazer a interface, no entanto, seriam apenas comentários internos e não seriam vistas na documentação online ou disponível para os clientes.

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


1

Criei uma ferramenta que pós-processa os arquivos de documentação XML para adicionar suporte à tag <herditdoc />.

Embora não ajude o 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 www.inheritdoc.io (versão gratuita disponível).


Observe que <herditdoc /> também é suportado pelo Sandcastle Help File Builder e está documentado aqui: ewsoftware.github.io/XMLCommentsGuide/html/… . Apenas percebi que isso também foi mencionado acima.
Olly

1

Você certamente pode comentar os dois, mas terá o problema de manter os dois (como mencionado anteriormente). No entanto, atualmente, qualquer código de consumo realmente não usará IoC / DI e não usará a interface? Dado isso, se você quiser apenas comentar um, sugiro fortemente que comente a interface. Dessa forma, o consumidor do seu código provavelmente terá as boas dicas de inteligência.


1

Uso de C #:

A interface pode ficar assim:

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

A implementação pode ser assim:

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.