Написание документации для C# проекта: от А до Я

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

Написание документации для C# проекта: от А до Я

Качественная документация — залог успешного и поддерживаемого C# проекта. Она помогает разработчикам быстро вникать в код, облегчает онбординг новых членов команды и снижает количество ошибок. В этой статье мы разберём полный процесс создания документации для C# (.NET) проекта: от основ XML-комментариев до автоматической генерации красивых сайтов.

1. Основы XML-комментариев в C#

Стандартный способ документирования кода в C# — XML-комментарии. Они пишутся перед объявлением класса, метода, свойства или другого элемента и начинаются с трёх слешей ///. Компилятор C# распознаёт эти комментарии и может генерировать XML-файл документации.

Вот базовые теги, которые вы будете использовать чаще всего:

<summary> — краткое описание элемента.
<param name="имя"> — описание параметра метода.
<returns> — описание возвращаемого значения.
<exception cref="Тип"> — описание исключения, которое может выбросить метод.
<example> — пример использования.
<remarks> — дополнительные примечания.

Пример правильного XML-комментария для метода:

/// <summary>
/// Вычисляет факториал целого неотрицательного числа.
/// </summary>
/// <param name="n">Целое неотрицательное число.</param>
/// <returns>Факториал числа n.</returns>
/// <exception cref="System.ArgumentException">Выбрасывается, если n меньше 0.</exception>
/// <example>
/// <code>
/// int result = Factorial(5);
/// // result равен 120
/// </code>
/// </example>
public static int Factorial(int n)
{
    if (n < 0)
        throw new ArgumentException("n не может быть отрицательным", nameof(n));

    int result = 1;
    for (int i = 1; i <= n; i++)
    {
        result *= i;
    }
    return result;
}

2. Документирование классов и свойств

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

Для свойств используйте теги <summary> и <value> (для описания хранимого значения):

/// <summary>
/// Представляет пользователя системы.
/// </summary>
public class User
{
    /// <summary>
    /// Уникальный идентификатор пользователя.
    /// </value>
    public int Id { get; set; }

    /// <summary>
    /// Полное имя пользователя.
    /// </summary>
    /// <value>Строка, содержащая имя и фамилию.</value>
    public string FullName { get; set; }

    /// <summary>
    /// Создаёт нового пользователя.
    /// </summary>
    /// <param name="id">Идентификатор.</param>
    /// <param name="fullName">Полное имя.</param>
    public User(int id, string fullName)
    {
        Id = id;
        FullName = fullName ?? throw new ArgumentNullException(nameof(fullName));
    }
}

3. Генерация XML-файла и сборка документации

Чтобы получить XML-файл из ваших комментариев, нужно настроить проект. В Visual Studio или через файл .csproj добавьте:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn> <!-- Отключает предупреждение о пропущенных комментариях, если нужно -->
</PropertyGroup>

После сборки проекта вы получите XML-файл, который можно использовать для создания красивой документации.

Для автоматической генерации сайта документации существуют два популярных инструмента:

Sandcastle Help File Builder (SHFB) — классический инструмент от Microsoft. Создаёт CHM, HTML, PDF.
DocFX — современный, быстрый и гибкий инструмент. Генерирует статический сайт, поддерживает Markdown и концепции "статей" (conceptual documentation).

Пример настройки DocFX:

// 1. Установите DocFX глобально:
// dotnet tool install -g docfx

// 2. Инициализируйте проект документации:
// docfx init

// 3. Укажите путь к вашему .sln или .csproj файлу в docfx.json

// 4. Соберите документацию:
// docfx build

// 5. Запустите локальный сервер для предпросмотра:
// docfx serve _site

DocFX автоматически прочитает XML-файлы, созданные компилятором, и сгенерирует красивый, современный сайт с навигацией, поиском и примерами кода.

4. Лучшие практики и советы

Чтобы документация была действительно полезной, следуйте этим простым правилам:

Пишите для людей. Избегайте фраз вроде "Этот метод делает то-то". Лучше: "Вычисляет корень квадратный из числа".
Документируйте "почему", а не "что". Код сам говорит "что" он делает. Документация должна объяснять мотивацию и контекст.
Обновляйте документацию вместе с кодом. Устаревшая документация хуже, чем её отсутствие. Добавьте проверку в CI/CD пайплайн.
Используйте <see cref="..." /> для создания ссылок на другие типы или методы.
Не документируйте тривиальное. Если метод называется GetName() и просто возвращает имя, комментарий "Возвращает имя" — избыточен.
Добавляйте примеры. Тег <example> — один из самых полезных. Он показывает, как использовать API на практике.