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

Question

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

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

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

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

Answer 1

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

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

Answer 2

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