Duplicazione della documentazione sulle implementazioni / sostituzioni dell'interfaccia buona o cattiva?

Quindi abbiamo un'interfaccia simile

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

Di recente, abbiamo riprodotto una storia di documentazione che prevedeva la generazione e la garanzia che ci fosse molta documentazione XML come sopra. Ciò ha causato tuttavia una duplicazione della documentazione. Esempio di implementazione:

/// <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
  }
}

Come puoi vedere, la documentazione del metodo è un semplice strappo dall'interfaccia.

La grande domanda è: è una brutta cosa? Il mio istinto mi dice di sì a causa della duplicazione, ma forse di nuovo no?

Inoltre, abbiamo un'altra duplicazione della documentazione simile con overridefunzioni e virtualfunzioni.

È cattivo e dovrebbe essere evitato o no? Ne vale la pena anche?

c# documentation xml documentation-generation

— Earlz
fonte

Se si utilizza Resharper, è possibile modificare i commenti solo nell'implementazione e quindi aggiornare l'interfaccia utilizzando "Copia membri".

— vortexwolf

Lo faccio ma forse perché non sono così bravo a usare strumenti esterni e preferisco semplicemente andare al file di intestazione di un'interfaccia per vedere cosa posso fare con un particolare tipo di cosa (questo è per C e C ++ che separano la nozione di intestazione dal file sorgente). Diventa un po 'ripetitivo ma provo a trovare opportunità per aggiungere dettagli più specifici relativi alla classe concreta che sovrascrive i metodi, ad esempio mi piace e ho una cosa OCD che va dove mi sento come se avessi omesso qualcosa di importante se non lo facessi vedere i commenti per ogni funzione in un file di intestazione.

In realtà utilizzo i commenti e i tag Doxygen ma in realtà non guardo molto ai documenti nel processo di codifica. Preferisco semplicemente andare al file di intestazione e vedere cosa posso fare con qualcosa. Potrebbe essere solo il caso di un vecchio cane che ha difficoltà a raccogliere nuove abitudini e strumenti.

In generale, aggiungerei nuova documentazione ai metodi di implementazione solo se c'è qualcosa di specifico in quella implementazione che deve essere menzionato.

In javadoc è possibile collegarsi ad altri metodi, il che consentirebbe di creare un collegamento nell'implementazione alla documentazione del metodo nell'interfaccia. Penso che sia così che dovrebbe essere fatto in .Net (basato sulla mia lettura della documentazione online, non sulla mia esperienza):

/// <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
  }
}

La documentazione per l' <see/>elemento: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

— FrustratedWithFormsDesigner
fonte

Che ne dici di sovrascrivere i documenti XML in una classe ereditata? Supponiamo di creare una sottoclasse Collection<T>e di voler sovrascrivere Counti documenti XML delle proprietà.

— Shimmy,