XML-комментарии в .NET: руководство

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

Логотип C#

Что такое XML-комментарии?

XML-комментарии — это особый вид комментариев в коде, который используют XML-теги для структурирования описаний типов, методов и свойств. Они помогают IDE показывать полезную справку при вызове методов, документировать параметры и возвращаемые значения, а также формировать внешнюю документацию с помощью генераторов типа DocFX или Sandcastle.

Определение в одну строку: XML-комментарий — это комментарий, начинающийся с трёх косых черт (///), с набором XML-тегов, описывающих API-элемент.

Как писать XML-комментарии

Чтобы быстро добавить шаблон XML-комментария в Visual Studio, поместите курсор над методом или типом и нажмите клавишу слэша три раза:

///

IDE автоматически создаст каркас с тегами

, и (если они применимы). Пример простого комментария:

/// 
/// Вычисляет сумму двух чисел.
/// 
/// Первое число.
/// Второе число.
/// Сумма a и b.
public int Add(int a, int b) => a + b;

Пример краткого комментария в .NET-коде.

Если у метода есть параметры или возвращаемое значение, Visual Studio сгенерирует поля для них. Когда вы используете метод, IntelliSense покажет содержимое

и подписи для параметров.

Нажмите клавишу слэша три раза (///) над методом, классом или другим типом, и Visual Studio вставит шаблон для заполнения.

Основные теги и их назначение

— краткое описание, показывается в IntelliSense.
— расширённая документация, обычно не показывается в подсказке IDE, но полезна в сгенерированных документах.
— описание возвращаемого значения метода.
— описание конкретного параметра метода (атрибут name обязателен).
— какие исключения может бросить метод и в каких случаях.
— для свойств, аналог для методов.
— пример использования; обычно внутри него помещают .
и — создают ссылки на другие члены API.
— позволяет вставлять упорядоченные или маркированные списки.

Пример с исключением и примером кода:

/// 
/// Делит число numerator на denominator.
/// 
/// Числитель.
/// Знаменатель.
/// Результат деления.
/// Если denominator равен нулю.
/// 
/// 
/// var result = Calculator.Divide(10, 2);
/// 
/// 
public double Divide(double numerator, double denominator) {
    if (denominator == 0) throw new DivideByZeroException();
    return numerator / denominator;
}

`Распространение и интеграция`

При сборке проекта компилятор C# может генерировать XML-файл документации (обычно с тем же именем, что и сборка). Если распространяете библиотеку, включите этот XML-файл вместе с .dll — тогда пользователи вашей библиотеки увидят ваши комментарии в своих IDE. Генераторы документации (DocFX, Sandcastle) принимают такие XML-файлы и преобразуют их в статические сайты и справочные страницы.

`Когда XML-комментарии не дают пользы`

Плохое или поверхностное содержание тега хуже, чем его отсутствие: лучше кратко и точно.
Когда API часто меняется, поддержание комментариев без автоматизации становится затратным и рискованным.
В неоднозначных местах комментарии не заменят хорошего дизайна API: сначала упростите сигнатуры, затем документируйте.

`Альтернативные подходы`

Автогенерация документации из тестов или BDD-спецификаций для поддержания документации в актуальном состоянии.
Внутри команды: использовать шаблоны PR, которые требуют заполнения XML-комментариев для публичных изменений API.
Комбинировать XML-комментарии с Markdown-файлами в репозитории для длинных руководств и сценарием использования.

`Руководство по качеству и чек-листы по ролям`

Чек-лист для разработчика перед пулл-реквестом:

Для каждого публичного типа/метода заполнён .
Для каждого параметра указан с понятным описанием.
Для методов, выбрасывающих исключения, добавлен .
Пример использования добавлен в при необходимости.

Чек-лист для ревьюера API:

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

`Практическая шпаргалка по тегам`

Коротко: , ,
Ошибки:
Ссылки:
Примеры: …
Списки: …

`Критерии приёмки`

Каждый публичный API-метод имеет непустой .
Описания параметров соответствуют именам и типам в сигнатуре.
Автотесты или CI проверяют генерацию XML-файла (опция компилятора включена).

`Ментальные модели и советы`

Документируйте намерение, а не реализацию: опишите «что делает» и «когда использовать», а не «как внутри реализовано».
Представьте себя пользователем API через 6–12 месяцев: какие вопросы у вас возникнут? Ответы должны быть в комментариях.

`Совместимость и миграция`

XML-комментарии лучше всего поддерживаются средами Microsoft (.NET, Visual Studio, VS Code с C# расширением). Другие языки и редакторы могут не иметь аналогичного уровня поддержки, поэтому при мульти-языковой библиотеке предпочтительнее общие внешние документационные сайты.

`Сводка`

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

Важно

XML-комментарии — это не замена архитектуре: чёткая сигнатура и понятные имена часто полезнее длинных комментариев.

Краткая памятка

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

1-строчный глоссарий

IntelliSense — система подсказок в IDE, показывающая сигнатуру и описание элементов API.
DocFX/Sandcastle — генераторы статической документации из XML-файлов.