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


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

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

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

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

2 5

2 ответа:

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

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

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