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

Question

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

Answer 1

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

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

(Это как старое правило "Ошибка может быть вне ваш код. Компиляторы тоже имеют ошибки. Это не один из тех случаев. ")

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

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

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

Answer 2

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

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

Answer 3

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