Я столкнулся с этой дилеммой при работе над веб-приложением ASP.net с использованием Web Client Software Factory (WCSF) в C #, и то же самое можно применить к другим платформам и языкам. Моя ситуация такова:
Я определяю интерфейс I View для каждой веб-страницы / пользовательского элемента управления на основе парадигмы WCSF, затем класс страницы реализует интерфейс I View, в основном реализуя каждый из методов, определенных в интерфейсе. Когда я попытался добавить xml-документацию на уровне метода, я обнаружил, что в основном повторяю одно и то же содержимое комментария как для метода интерфейса, так и его аналога в реализующем классе.
Итак, мой вопрос: должна ли существовать существенная разница между содержанием документации по методу интерфейса и методу соответствующего класса? Должны ли они акцентировать внимание на другом аспекте или что-то?
Кто-то сказал мне, что комментарий метода интерфейса должен сказать «что» должен делать метод, а комментарий метода класса должен сказать «как» он это делает. Но я помню, как читал где-то раньше, что комментарий уровня метода должен только говорить «что» должен делать метод, а не детали реализации метода, поскольку реализация не должна беспокоить пользователей метода и может измениться.