Прокоментувати інтерфейс, реалізацію чи те й інше?

Я думаю, що всі ми (коли нас може турбувати!) Коментують наші інтерфейси. напр

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

Ви також коментуєте реалізацію (яка також може бути надана клієнтам, наприклад, як частина бібліотеки aa)? Якщо так, як вам вдається синхронізувати їх? Або ви просто додаєте коментар "Див інтерфейс документації"?

Дякую

Як правило, я використовую той же принцип DRY (не повторюй себе), як і для коду:

• на інтерфейс, документуйте інтерфейс
• щодо впровадження, документуйте особливості реалізації

Специфічна для Java : під час документування реалізації використовуйте тег {@inheritDoc}, щоб "включити" javadocs з інтерфейсу.

Для отримання додаткової інформації:

• Офіційна документація на javadoc
• Деякі неофіційні поради .

Якщо ви використовуєте додаток GhostDoc , він оновлює реалізацію за допомогою коментаря з інтерфейсу, коли клацніть правою кнопкою миші та виберіть "Документ це" в методі.

Для C # це залежить від IMO: Якщо ви використовуєте явні реалізації інтерфейсу, я б не документував реалізацію.

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

Як сказала Nath, ви можете використовувати GhostDoc для автоматичного вставлення документації інтерфейсу в реалізацію. Я відобразив документ Дана команда на ярлику Ctrl + Shift + D і її одному з натискань клавіш, які я майже автоматично натискаю. Я вважаю, що ReSharper також має можливість вставити документацію інтерфейсу, коли він реалізує методи для вас.

Тільки інтерфейс. Коментування обох є дублюванням, і цілком ймовірно, що два набори коментарів згодом вийдуть із синхронізації, якщо код зміниться. Прокоментуйте реалізацію за допомогою "реалізує MyInterface" ... Такі речі, як Doxygen, генерують документи, які включають похідні документи в документи для реалізації в будь-якому випадку (якщо ви їх правильно налаштували).

Ми просто коментуємо інтерфейс, коментарі так легко вийти з синхронізації з похідним або базовим класом / інтерфейсом, що приємно мати його лише в одному місці.

Хоча це схоже на @Nath, можливо, пропонує автоматизований інструмент документації, який допомагає тримати речі разом (звучить круто, якщо ви користуєтесь цим). Тут у WhereIWorkAndYouDontCare коментарі призначені для розробників, тому одне місце в коді є кращим

Коментуючи інтерфейс, має бути достатньо документації, щоб визначити, як використовувати фактичну реалізацію. Єдиний раз, коли я додаю коментарі до реалізації, це якщо у неї є приватні функції, які були вставлені для задоволення інтерфейсу, однак вони були б лише внутрішніми коментарями і не були б помічені в документації в Інтернеті чи доступній для клієнтів.

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

Я створив інструмент, який після обробки файлів документації XML додає підтримку тегу <nasleditdoc />.

Хоча він не допомагає Intellisense у вихідному коді, він дозволяє включити змінені файли документації XML до пакету NuGet і, отже, працює з Intellisense у посилах NuGet.

Це на сайті www.inheritdoc.io (безкоштовна версія доступна).

Ви, звичайно, можете коментувати і те, і інше, але тоді у вас є проблема збереження обох (як уже згадувалося). Однак в цей день чи вік якийсь споживчий код дійсно не використовує IoC / DI і не використовує інтерфейс? Враховуючи це, якщо ви хочете лише заперечувати коментарі, я настійно пропоную прокоментувати інтерфейс. Таким чином споживач вашого коду швидше за все отримає приємні підказки про інтелігенцію.

Використання C #:

Інтерфейс може виглядати так:

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

Реалізація може виглядати приблизно так:

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