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

Question

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

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

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

Спасибо

Answer 1

Как правило, я использую тот же принцип СУХОГО (не повторяй себя), что и с кодом:

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

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

Для получения дополнительной информации:

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

Answer 2

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

Answer 3

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

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

Answer 4

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

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

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

Answer 5

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

Answer 6

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

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

Answer 7

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

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

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