Комментарии XML в исходном коде для производных классов или реализаций интерфейса

Question

Относится к моему предыдущему вопросу. Если я определю интерфейс, я прокомментирую его участников. Затем я не комментирую реализацию класса реализации, если нет причины, по которой исходный комментарий больше не действителен.

Решарпер в порядке, Visual Studio утверждает, что это предупреждение.

Важно, что унаследованные комментарии отображаются через intellisense, когда вы работаете с ними, что является моей единственной реальной проблемой.

Что вы думаете об этом?

Спасибо

Answer 1

Я только что столкнулся с той же «проблемой», и я думаю, что Visual Studio правильно сообщает о запахе кода.

Ваша проблема, если я правильно понимаю, состоит в том, что не DRY иметь столько же комментариев к вашему интерфейсу и вашей реализации. Это имеет большой смысл - большую часть времени, особенно когда вы издеваетесь и тестируете, код будет использовать интерфейс, а не реализацию, когда она у вас есть. Зачем дублировать?

Бьюсь об заклад, ваш класс отмечен public. В этом случае класс МОЖЕТ использоваться без интерфейса с помощью внешнего кода . Эти внешние пользователи заслуживают некоторых комментариев, и вы никогда не узнаете, когда у вас есть дополнительные общедоступные методы, которые не отражены в списке интерфейсов, которые вы реализуете. Прокомментируйте это!

Однако, если вы не хотите делать эти комментарии (по крайней мере, в VS 2017; я понимаю, что вы использовали 2013, который мне не пригодился), вы можете отметить реализующий класс internal и пропустите комментарии .

И тогда ваша проблема с комментариями на СУХОЙ будет решена.

Answer 2

Добавление комментариев к вашему коду - это всегда хорошая практика.Если компонент является закрытым или внутренним классом, и он всегда будет доступен через известный интерфейс или абстрактный класс, в котором есть все комментарии, то вам может потребоваться только прокомментировать определенные вещи в реализации этого класса (например, есличем один человек будет смотреть на код, или если вы вернетесь к своему коду через несколько лет).Таким образом, будет легче понять, что делает код и почему.Если вы включили создание XML-документации при создании проекта, Visual Studio предупредит вас о недокументированных членах.

Я также получаю предупреждения Resharper для некоторых классов, когда я включаю генерацию XML-документации, но Resharper предупреждает только для элементов с публичной видимостью.Чтобы сократить работу над документацией, я бы рекомендовал сначала комментировать открытые классы и интерфейсы (особенно, если вы выпускаете библиотеку продуктов), и, если есть достаточно времени, внутренние / частные.Если вы решите не комментировать последнее, просто убедитесь, что вы или кто-либо, кто будет работать с кодом, легко поймут логику и причины этого.