Дублирование документации по реализации / переопределениям интерфейса хорошо или плохо?

Итак, у нас есть такой интерфейс

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

— Earlz
источник

Если вы используете Resharper, вы можете изменять комментарии только в реализации, а затем обновлять интерфейс с помощью «Подтянуть членов вверх».

— vortexwolf

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

Я на самом деле использую комментарии и теги 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-документов.

— Шимми