Czy powielanie dokumentacji dotyczącej implementacji / zastąpień interfejsu jest dobre czy złe?

Mamy więc taki interfejs

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

Niedawno odtworzyliśmy historię dokumentacji, która polegała na wygenerowaniu i zapewnieniu dużej ilości dokumentacji XML, jak wyżej. Spowodowało to jednak znaczne powielanie dokumentacji. Przykładowa implementacja:

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

Jak widać, dokumentacja metody jest prostym zgrywaniem z interfejsu.

Najważniejsze pytanie brzmi: czy to źle? Moje jelita mówi mi tak z powodu duplikacji, ale z drugiej strony może nie?

Mamy też inne podobne powielanie dokumentacji z overridefunkcjami i virtualfunkcjami.

Czy to jest złe i należy tego unikać, czy nie? Czy to w ogóle się opłaca?

c# documentation xml documentation-generation

— Earlz
źródło

Jeśli używasz Resharpera, możesz zmieniać komentarze tylko we wdrożeniu, a następnie aktualizować interfejs za pomocą „Podciągnij członków w górę”.

— vortexwolf

Robię to, ale może dlatego, że nie jestem zbyt dobry w korzystaniu z narzędzi zewnętrznych i wolę po prostu przejść do pliku nagłówka interfejsu, aby zobaczyć, co mogę zrobić z określonym rodzajem rzeczy (dotyczy to C i C ++, które oddzielają pojęcie nagłówka z pliku źródłowego). Robi się to trochę powtarzalne, ale staram się znaleźć możliwości dodania bardziej szczegółowych szczegółów dotyczących konkretnej klasy przesłaniającej metody, np. Podoba mi się i mam problem z OCD, w którym czuję się, jakbym pominął coś ważnego, jeśli nie zobacz komentarze do każdej funkcji w pliku nagłówkowym.

Właściwie używam komentarzy i tagów Doxygen, ale tak naprawdę nie patrzę tak bardzo na dokumenty w trakcie kodowania. Wolę po prostu przejść do pliku nagłówka i zobaczyć, co mogę z czymś zrobić. Może to być przypadek, w którym stary pies ma trudności z nabyciem nowych nawyków i narzędzi.

Ogólnie rzecz biorąc, dodawałbym nową dokumentację do metod implementacji tylko wtedy, gdy jest coś konkretnego w tej implementacji, o czym trzeba wspomnieć.

W javadoc możesz połączyć się z innymi metodami, które pozwoliłyby ci po prostu utworzyć link w implementacji do dokumentacji metody w interfejsie. Myślę, że tak powinno się to odbywać w .Net (na podstawie mojej lektury dokumentacji online, a nie własnego doświadczenia):

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

Dokumentacja <see/>elementu: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

— FrustratedWithFormsDesigner
źródło

Co powiesz na przesłanianie dokumentów XML w odziedziczonej klasie? Powiedzmy, że utworzyłem podklasę Collection<T>i chcę zastąpić jej Countwłaściwości dokumenty XML.

— Shimmy