Прокомментируйте интерфейс, реализацию или и то, и другое?

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

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

Вы также комментируете реализацию (которая также может быть предоставлена ​​клиентам, например, как часть библиотеки)? Если да, то как вам удается синхронизировать их? Или вы просто добавляете комментарий «См. Интерфейс для документации»?

Спасибо

Как правило, я использую тот же принцип DRY (Don't Repeat Yourself), что и в коде:

• на интерфейсе, задокументируйте интерфейс
• по реализации документально оформить особенности реализации

Специфика Java : при документировании реализации используйте тег {@inheritDoc}, чтобы «включить» документы javadoc из интерфейса.

Чтобы получить больше информации:

• Официальная документация javadoc
• Неофициальный совет .

Если вы используете надстройку GhostDoc , она обновляет реализацию с помощью комментария из интерфейса, когда вы щелкаете правой кнопкой мыши и выбираете «Документировать это» в методе.

Для C # это зависит от IMO: если вы используете явные реализации интерфейса, я бы не стал документировать реализацию.

Однако, если вы реализуете интерфейс напрямую и раскрываете элементы интерфейса с вашим объектом, эти методы также должны быть задокументированы.

Как сказал Нат, вы можете использовать GhostDoc для автоматической вставки документации интерфейса в реализацию. Я сопоставил команду Document This с сочетанием клавиш Ctrl + Shift + D и одним из клавиш, которые я нажимаю почти автоматически. Я считаю, что ReSharper также имеет возможность вставлять документацию интерфейса, когда он реализует методы за вас.

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

Мы просто комментируем интерфейс, комментарии так легко рассинхронизировать с производным или базовым классом / интерфейсом, что приятно иметь его только в одном месте.

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

Комментируя интерфейс, должно быть достаточно документации, чтобы понять, как использовать реальную реализацию. Единственный раз, когда я хотел бы добавить комментарии к реализации, это если бы она имела частные функции, которые были вставлены для удовлетворения интерфейса, однако они будут только внутренними комментариями и не будут отображаться в документации в Интернете или доступны для клиентов.

Реализации - это просто так, пока они соответствуют интерфейсу, нет необходимости документировать их отдельно.

Я создал инструмент, который пост-обрабатывает файлы документации XML, чтобы добавить поддержку тега <inheritdoc />.

Хотя он не помогает с Intellisense в исходном коде, он позволяет включать измененные файлы XML-документации в пакет NuGet и, следовательно, работает с Intellisense в указанных пакетах NuGet.

Это на www.inheritdoc.io (доступна бесплатная версия).

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

Использование 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();
    }
}