Skomentuj interfejs, implementację czy jedno i drugie?

Wyobrażam sobie, że wszyscy (kiedy możemy się martwić!) Komentujemy nasze interfejsy. na przykład

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
    /// <summary>
    /// Will 'bar'
    /// </summary>
    /// <param name="wibble">Wibble factor</param>
    void Bar(string wibble);
}

Czy komentujesz również implementację (która może być również udostępniona klientom, np. W ramach biblioteki aa)? Jeśli tak, jak radzisz sobie z utrzymaniem synchronizacji tych dwóch? A może po prostu dodajesz komentarz „Zobacz interfejs w celu uzyskania dokumentacji”?

Dzięki

Generalnie używam tej samej zasady DRY (Don't Repeat Yourself) jak w przypadku kodu:

• na interfejsie, udokumentuj interfejs
• na wdrożeniu udokumentuj specyfikę wdrożenia

Specyficzne dla języka Java : podczas dokumentowania implementacji użyj tagu {@inheritDoc}, aby „dołączyć” javadocs z poziomu interfejsu.

Po więcej informacji:

• Oficjalna dokumentacja javadoc
• Nieoficjalna rada .

Jeśli używasz dodatku GhostDoc, aktualizuje on implementację komentarzem z interfejsu po kliknięciu prawym przyciskiem myszy i wybraniu opcji „Dokumentuj to” w metodzie.

W przypadku C # zależy to od IMO: Jeśli używasz jawnych implementacji interfejsu, nie dokumentowałbym implementacji.

Jeśli jednak implementujesz interfejs bezpośrednio i ujawniasz elementy członkowskie interfejsu z obiektem, te metody również muszą być udokumentowane.

Jak powiedział Nath, możesz użyć GhostDoc do automatycznego wstawienia dokumentacji interfejsu do implementacji. Zmapowałem polecenie Document This do skrótu Ctrl + Shift + D i jest to jedno z klawiszy, które prawie automatycznie naciskam. Uważam, że ReSharper ma również opcję wstawiania dokumentacji interfejsu, gdy implementuje metody za Ciebie.

Tylko interfejs. Komentowanie obu jest duplikacją i jest prawdopodobne, że oba zestawy komentarzy ostatecznie stracą synchronizację, jeśli zmieni się kod. Skomentuj implementację słowem „implementuje MyInterface” ... Rzeczy takie jak Doxygen generują dokumenty, które i tak zawierają dokumenty pochodne w dokumentach do implementacji (jeśli ustawisz je poprawnie).

Po prostu komentujemy interfejs, komentarze są tak łatwe do zsynchronizowania z klasą / interfejsem pochodną lub podstawową, że dobrze jest mieć je w jednym miejscu.

Chociaż wygląda na to, że @Nath może sugerować automatyczne narzędzie do dokumentacji, które pomaga utrzymać wszystko razem (brzmi fajnie, jeśli go używasz). Tutaj w WhereIWorkAndYouDontCare komentarze są dla programistów, więc preferowane jest jedno miejsce w kodzie

Komentowanie interfejsu powinno być wystarczającą dokumentacją, aby dowiedzieć się, jak korzystać z rzeczywistej implementacji. Jedyny moment, w którym dodałbym komentarze do implementacji, to gdyby zawierała prywatne funkcje, które zostały wstawione w celu zaspokojenia interfejsu, jednak byłyby to tylko komentarze wewnętrzne i nie byłyby widoczne w dokumentacji online lub dostępne dla klientów.

Implementacje są po prostu takie, o ile są zgodne z interfejsem, nie ma potrzeby dokumentowania ich osobno.

Użycie C #:

Interfejs może wyglądać następująco:

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

Implementacja może wyglądać następująco:

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}

Stworzyłem narzędzie, które post-przetwarza pliki dokumentacji XML, aby dodać obsługę tagu <inheritdoc />.

Chociaż nie pomaga to w przypadku Intellisense w kodzie źródłowym, umożliwia uwzględnienie zmodyfikowanych plików dokumentacji XML w pakiecie NuGet i dlatego współpracuje z Intellisense w przywoływanych pakietach NuGet.

Jest na www.inheritdoc.io (dostępna jest darmowa wersja).

Z pewnością możesz skomentować oba, ale wtedy masz problem z utrzymaniem obu (jak wspomniano wcześniej). Jednak w dzisiejszych czasach jakikolwiek konsumujący kod naprawdę nie będzie używał IoC / DI i nie będzie używał interfejsu? Biorąc to pod uwagę, jeśli chcesz tylko zawracać sobie głowę komentarzem, zdecydowanie sugeruję skomentowanie interfejsu. W ten sposób konsument Twojego kodu najprawdopodobniej otrzyma przyjemne wskazówki dotyczące inteligencji.