XML-комментарии C#: Сколько <видит …/>, ссылки в XML-комментариях полезны?

Лично я думаю, что то, что у вас есть, немного переборщило.

Целью «см.» Ссылок является обеспечение хорошей связи между темами в сгенерированной справочной документации после анализа.

] В вашем случае ваши бизнес-библиотеки ссылаются на языковые элементы, например:

<see langword="true"/>

Я лично считаю, что гиперссылки на другие связанные объекты в вашей библиотеке являются очень полезной функцией. Это делает чтение справки более удобным для пользователей.

Гиперссылки на языковые элементы - это то, что, как мне кажется, должно существовать только внутри самой языковой справки. В случае сторонней библиотеки это просто "запутывает" сообщение, помещая ссылки повсюду. Это делает хорошие ссылки менее эффективными, поскольку они прячутся в беспорядке.

Я бы посоветовал свободно использовать ссылки на родственные классы в вашей библиотеке. Я бы не стал добавлять гиперссылки на классы базовых библиотек, за исключением конкретных случаев, когда это по какой-то причине особенно полезно (редко). Ссылки на «true» и «IDisposable.Dispose» и т. Д. На самом деле не добавляют большой ценности.

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

Суть всех этих заключается в том, что когда что-то вроде Sandcastle используется для создания документов HTML или CHM для библиотеки, эти документы получают навигацию между объектами по гиперссылкам. Итак, вопрос в том,

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

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

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

Когда вы работаете с Visual Studio, вы можете использовать плагин CR_Documentor (он бесплатный, вы можете получить его здесь ) для WYSiWYG-чтения / написания ваших комментариев. . Похоже, справка сгенерирована из Sandcastle или NDoc, но отображается на лету. Это действительно полезно, и вам вообще не нужно заботиться о необработанных комментариях XML.

Как сказал ctacke, это очень полезно для создания гиперссылок. Однако, если вы на самом деле не отправляете документацию, все эти теги делают документацию практически невозможной для чтения. В этом случае документация предназначена для (редактировать: ВНУТРЕННИЙ) разработчика, и если он или она не может ее прочитать, вы зря теряете время.

Как правило, я предпочитаю первую ссылку на тип или член, а остальные оставьте несвязанными. Он оставляет комментарии довольно чистыми и по-прежнему обеспечивает значимые ссылки.