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

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

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

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

Спасибо

ОТВЕТЫ

Ответ 1

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

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

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

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

Ответ 2

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

Ответ 3

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

Ответ 4

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

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

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

Ответ 5

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

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

Ответ 6

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

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

Ответ 7

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

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

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