Código Comentando: Você colocar seus comentários de código em Interfaces ou em classes concretas, ou ambos? [duplicado]

Question

Esta questão já tem uma resposta aqui:

• Comente a interface, implementação ou ambos? 8 respostas

O que é a melhor prática em documentar classes e interfaces. Diga se você tiver uma classe concreta chamado Foo, que deriva de uma interface chamada IFoo. Onde você colocar seus comentários para os seus métodos? Você duplicar os seus comentários sobre a interface, bem como a classe concreta?

Aqui está um exemplo onde os comentários são duplicados:

public class Foo : IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    public void DoSomething()
    {
    }
}

public interface IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    void DoSomething();
}

Answer 1

Gostaria de colocar comentários em ambos.

Em interfaces de I quis comentar sobre a intenção por trás os membros de interface e utilização.

Em implementações que eu gostaria de comentar sobre as razões para a implementação específica.

Answer 2

Eu geralmente colocá-los em ambos, no entanto, eles não dizem a mesma coisa. O comentário do interface deve descrever a finalidade resumo deste método / interface. Enquanto o comentário de concreto vai falar sobre os detalhes de implementação do método / classe no contexto do propósito do interface.

Answer 3

eu colocá-los em ambos, mas é uma dor mantê-los em sincronia, quando em dúvida eu só colocá-los na interface.

Eu faço isso porque eu como a dica de ferramenta quando usando o código, que quase sempre deve estar usando a interface ...

Answer 4

O código de exemplo não usa implementação de interface explícita. O cliente do seu código vai precisar de ambos desde que ele / ela pode invocar o método seja através de um objeto de classe ou de referência interface. Com a implementação de interface explícita pode omitir o comentário método de classe uma vez que o cliente nunca pode vê-lo. Isso supõe que você está usando documentação XML para gerar informações IntelliSense.

Answer 5

Ambos, mas eu gostaria que foi construído em funcionalidade para mantê-los em sincronia

Answer 6

A <referTo>System. .... </referTo> tag para ligar os comentários seria ideal

Answer 7

Eu realmente não usá-los em tudo. Em vez disso eu certifique-se de estruturar o código e nomear todos os métodos e variáveis ??de uma forma que é óbvio que eles fazem sem comentários. O problema com os comentários é que eles não compilar e não executar e não são testados por seus testes de unidade, pelo que a sua praticamente impossível para mantê-los em sincronia com o código.

Answer 8

Apenas para interfaces. Porque neste caso eu não preciso sincronizá-los. Meu IDE me ajuda a ver comentários de interface em classes concretas. E gerador de documentos api faz o mesmo.

Answer 9

O ideal é que apenas as necessidades de interface a serem documentadas, uma vez que define o contrato que todas as necessidades de implementação concreta para cumprir.