it-roy-ru.com

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

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

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

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

Спасибо

108
ng5000

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

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

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

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

87
Neeme Praks

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

7
NikolaiDante

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

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

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

4
grover

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

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

4
Jiminy

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

3
Len Holgate

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

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

2
X-Istence

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

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

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

0
K Johnson