Duplicar a documentação sobre implementações / substituições de interface é bom ou ruim?

20

Então nós temos uma interface assim

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

Recentemente, reproduzimos uma história de documentação que envolvia a geração e a garantia de que havia muita documentação XML como acima. Isso causou muita duplicação de documentação. Exemplo de implementação:

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

Como você pode ver, a documentação do método é uma cópia direta da interface.

A grande questão é: isso é ruim? Meu intestino me diz que sim por causa da duplicação, mas talvez não?

Além disso, temos outra duplicação de documentação semelhante com overridefunções e virtualfunções.

Isso é ruim e deve ser evitado ou não? Vale a pena mesmo?

c# documentation xml documentation-generation Earlz
fonte
Se você usar o Resharper, poderá alterar os comentários apenas na implementação e atualizar a interface usando "Puxe membros para cima".
precisa saber é o seguinte
Eu faço isso, mas talvez porque eu não seja tão bom em usar ferramentas externas e prefira apenas navegar no arquivo de cabeçalho de uma interface para ver o que posso fazer com um tipo específico de coisa (isso é para C e C ++ que separam a noção de cabeçalho do arquivo de origem). Fica um pouco repetitivo, mas tento encontrar oportunidades para adicionar detalhes mais específicos relacionados à classe concreta que substitui os métodos, por exemplo, eu gosto e tenho uma coisa do TOC em que sinto que omiti algo importante se não o fizesse. veja comentários para todas as funções em um arquivo de cabeçalho.
Na verdade, eu uso comentários e tags do Doxygen, mas na verdade não olho muito para os documentos no processo de codificação. Prefiro simplesmente navegar até o arquivo de cabeçalho e ver o que posso fazer com alguma coisa. Pode ser apenas o caso de um cachorro velho que está com dificuldades para adquirir novos hábitos e ferramentas.

Respostas:

9

Em geral, eu só adicionaria nova documentação aos métodos da implementação se houver algo específico sobre essa implementação que precise ser mencionado.

No javadoc, você pode vincular a outros métodos, o que permitiria criar apenas um link na implementação para a documentação do método na interface. Acho que é assim que deve ser feito no .Net (com base na leitura da documentação on-line, não na minha própria experiência):

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// <see cref="ICreatesFoo.Create(Foo)"/>
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// <see cref="ICreatesFoo.Bar()"/>
  /// Also Note: Implementation of Bar() in FastFooCreator
  /// requires a minimum of 512 MB RAM to Bar the Foo. 
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

A documentação para o <see/>elemento: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

FrustratedWithFormsDesigner
fonte
Que tal substituir os documentos XML em uma classe herdada? Digamos que eu faça uma subclasse de Collection<T>e queira substituir seus Countdocumentos XML de propriedade.
Shimmy