Комментировать интерфейс, реализацию или и то, и другое?
Я предполагаю, что мы все (когда нас могут беспокоить!) комментировать наши интерфейсы. например.
/// <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(доступна бесплатная версия).