Comentar a interface, implementação ou ambos?

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

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:

• Documentação oficial do javadoc
• Alguns conselhos não oficiais .

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.

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

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

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

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.

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

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.

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();
    }
}