Дублювання документації щодо реалізації / переопределення інтерфейсу добре чи погано?

Отже, у нас є такий інтерфейс

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

Нещодавно ми розігрували історію документації, яка передбачала створення та забезпечення достатньої кількості XML-документації, як вище. Однак це спричинило багато дублювання документації. Приклад реалізації:

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

Як ви бачите, документація методу - це прямий відрив інтерфейсу.

Велике питання - це погана справа? Моя кишка каже мені так через дублювання, але потім, можливо, ні?

Також у нас є інша аналогічна копія документації з overrideфункціями та virtualфункціями.

Це погано і цього слід уникати, чи ні? Це взагалі варте того?

c# documentation xml documentation-generation

— Граф
джерело

Якщо ви використовуєте Resharper, ви можете змінювати коментарі лише під час реалізації, а потім оновлювати інтерфейс, використовуючи "Потягніть членів".

— vortexwolf

Я це роблю, але, можливо, тому, що я не так добре використовую зовнішні інструменти і вважаю за краще просто перейти до заголовкового файлу інтерфейсу, щоб побачити, що я можу зробити з певним типом речі (це для C і C ++, які відокремлюють поняття заголовка з вихідного файлу). Це стає дещо повторюваним, але я намагаюся знайти можливості додати більш конкретні деталі, що стосуються конкретного класу, що переважає методи, наприклад, мені це подобається, і я маю на увазі те, що я відчуваю, що я пропустив щось важливе, якщо я цього не роблю переглянути коментарі до кожної функції у файлі заголовка.

Я фактично використовую коментарі та теги Doxygen, але насправді не дивлюся на документи так сильно в процесі кодування. Я вважаю за краще просто перейти до заголовкового файлу і подивитися, що я можу з чим-небудь зробити. Це може бути випадком старого собаки, який важко підбирає нові звички та інструменти.

Загалом, я додаю нову документацію до методів впровадження лише в тому випадку, якщо є щось конкретне щодо цієї реалізації, яке потрібно згадати.

У javadoc ви можете посилатися на інші методи, які дозволять вам просто створити посилання в реалізації на документацію методу в інтерфейсі. Я думаю, що саме так слід робити в .Net (на основі мого читання онлайн-документації, а не власного досвіду):

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

Документація для <see/>елемента: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

— FrustratedWithFormsDesigner
джерело

Як щодо перекриття документів XML у спадковому класі? Скажіть, я роблю підклас Collection<T>і хочу переосмислити його Countвластивості на XML-документи.

— Шиммі