Рекомендации по использованию C# Intellisense Комментарии

Question

У нас есть решение Visual Studio 2010, которое содержит несколько проектов на C# в соответствии с рисунком архитектуры Луны Джеффри Палермо (http://jeffreypalermo.com/blog/the-onion-architecture-part-1/). Мы хотим добавить комментарии Visual Studio Intellisense, используя тройную косую черту, но мы хотим узнать, знает ли кто-нибудь о лучших методах, как это можно сделать. Заходим ли мы в проект Model в Core, и работаем через Infrastructure и в DataAccess Services и Repositories и в пользовательский интерфейс? Или лучше использовать эти комментарии более ограниченным образом, и если да, то каковы важные объекты для применения комментариев Intellisense?

Answer 1

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

По-прежнему полезно добавлять эти комментарии к закрытым методам, я делаю это в любом случае, чтобы быть последовательным. Это также помогает, если вы планируете генерировать документацию из комментариев.

Answer 2

В то время как технически существует такая вещь, как слишком большая документация, 99.99999% времени, когда это исключение не применяется.

Документируйте все как можно больше. Формальный, неформальный, поток мысли ... всякий комментарий комментариев поможет некоторым бедным духам, которые наследуют ваш код или должны взаимодействовать с ним.

(Это как старое правило «Ошибка может быть в компиляторе, а не код. Составители имеют ошибки тоже. Это не один из тех времен.»)

ли мы начинаем весь путь вниз модель в проекте Core, а также работать через инфраструктуру и в службы и репозитории DataAccess и в пользовательский интерфейс? Да

Или лучше использовать эти комментарии более ограниченным образом, и если да, то каковы важные объекты для применения комментариев Intellisense? Если вы хотите. Примените их к любой функции, которую вы пишете, а не к тому, что VS автогенерирует

Я видел ограниченные комментарии «intellisense» .. но обширные комментарии в коде, которые следуют. Пока «содержание» есть, жизнь будет хорошей. Обычно я включаю краткое описание каждой функции в комментариях intellisense, но большинство из них «вот почему я сделал это» в функциональных и мертвых документах.

Answer 3

Я согласен с fletcher. Начните с открытых классов и методов, а затем перейдите в частный код. Если вы начинаете с нуля, я бы настоятельно рекомендовал добавлять комментарии XML ко всему коду для вашего удобства, но в этом случае, начиная с общедоступных методов, а затем обновлять другие классы, когда вы собираетесь их обновлять, это хорошее решение.