Как должен комментарии для методов интерфейса и методов класса отличаться

Я столкнулся с этой дилеммой при работе над веб-приложением ASP.net с помощью Фабрики программного обеспечения веб-клиента (WCSF) в C#, и то же могло относиться к другой платформе и языкам. Моя ситуация похожа на это:

Я определяю интерфейс IView для каждой веб-страницы / пользовательский элемент управления на основе парадигмы WCSF, затем имею реализацию класса страницы интерфейс IView, в основном реализовывая каждый из методов, определенных в интерфейсе. Когда я пытался добавить xml-документацию на уровне метода, я повторил в основном то же содержание комментария и для метода интерфейса и для его дубликата в классе с реализацией.

Таким образом, мой вопрос: должны быть некоторые существенные различия между содержанием документации на методе интерфейса и соответствующим методом класса? Они должны подчеркивать на другом аспекте или чем-то?

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

5
задан hongliang 5 March 2010 в 19:21
поделиться

2 ответа

Лично я думаю, что эти комментарии должны быть одинаковыми - оба должны сказать, «что будет делать метод», в ваших терминах.

В комментариях XML нет причин упоминать детали реализации. Единственным исключением, возможно, было бы упоминание потенциальных побочных эффектов (то есть: этот метод может занять много времени), но я лично сделал бы это в разделе комментариев к XML-документу.

8
ответ дан 13 December 2019 в 05:34
поделиться

Считайте меня психом, но я бы использовал описательное имя для метода и на этом закончил (без комментариев). Я мог бы добавить комментарии к реализации, если что-то в ней удивит или если ее применение неочевидно.

4
ответ дан 13 December 2019 в 05:34
поделиться
Другие вопросы по тегам:

Похожие вопросы: