комментариев

Что такое комментарии

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

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

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

Виды комментариев

Тип комментария	Начальный маркер	Конечный маркер	Основные правила
Однострочный Single-line	//	Конец текущей строки	Действует только для одной строки, весь текст после // игнорируется
Блочный Delimited	/*	*/	Охватывает несколько строк или фрагмент внутри строки, вложенность не поддерживается
Документационный Documentation	///	Конец текущей строки	Поддерживает XML-теги, используется для автоматической генерации API-документации проекта

1. Однострочные комментарии //

1. Компилятор игнорирует всё, начиная с // до самого конца текущей строки;
2. Можно размещать в начале строки или после рабочего кода;
3. Нет ограничений на вложенность, не возникает конфликтов с блочными комментариями /* */.

// Однострочный комментарий в начале строки: объявление числовой переменной
int num = 10; // Однострочный комментарий после кода: хранит значение 10
// int temp = 99; // Вся строка закомментирована для отладки; временно отключает код без удаления, легко восстановить позжеCode language: JavaScript (javascript)

2. Блочные комментарии /* */

1. Требуется пара маркеров открытия и закрытия, всё между /* и */ игнорируется;
2. Поддерживается охват нескольких строк и частичное комментирование внутри одной строки;
3. Вложение блочных комментариев запрещено. Компилятор завершает комментарий на первом встреченном */, оставшиеся незакрытые маркеры */ вызовут синтаксическую ошибку.

Пример

/*
Пример многострочного блочного комментария
Компилятор пропускает всё содержимое
Можно писать текст на любом количестве строк
*/
string str = "Тест";Code language: JavaScript (javascript)

/*
Multi-line delimited comment example
All content here is ignored by the compiler
Text can span any number of lines
wellcome to foxdevelop.com
*/
string greet = "wellcome to foxdevelop.com";
Console.WriteLine(greet);Code language: JavaScript (javascript)

Вложение вызывает ошибку компиляции

Если внутри одного блочного комментария разместить второй, последний закрывающий маркер останется без соответствующего открывающего, что приведёт к ошибке синтаксиса.

Частичные комментарии внутри строки

Закомментирует только фрагмент кода; в примере ниже переменная a полностью скрыта комментарием.

int /*a,*/ b; 
// Эквивалентно int b; фрагмент a, между маркерами игнорируетсяCode language: JavaScript (javascript)

Неверный пример вложенного блочного комментария

Вызывает ошибку сборки

/* Начало внешнего комментария
    /* Вложенный внутренний комментарий (воспринимается как обычный текст) */
// Первый */ выше закрывает внешний блок, оставшийся */ без открытия создаёт синтаксическую ошибку
*/Code language: JavaScript (javascript)

/* внутри // не активирует блочный комментарий

В данном случае маркеры блочного комментария являются обычным текстом внутри однострочного комментария и не работают.

// Это однострочный комментарий /* символ здесь просто текст, блочный комментарий не открывается
int x = 5;
/* Открываем блочный комментарий */ // Блок закрыт здесь, последующий // работает как обычноCode language: JavaScript (javascript)

3. Документационные комментарии ///

1. Внешне похожи на однострочные, обозначаются тремя косыми чертами ///;
2. Поддерживают встроенные XML-теги, среды разработки считывают их для генерации справочной API-документации;
3. Обычно размещаются над классами, методами и свойствами для описания общедоступных интерфейсов.

/// <summary>
/// Основной класс, точка входа приложения
/// </summary>
class Program
{
    /// <summary>
    /// Метод входа в программу
    /// </summary>
    /// <param name="args">Массив аргументов командной строки</param>
    static void Main(string[] args)
    {

    }
}Code language: JavaScript (javascript)

Итог

1. Блочные комментарии /* */ не поддерживают вложенность, парсинг прекращается при первом встреченном */;
2. Однострочные // действуют только в пределах своей строки, не переходят на другие строки, любое /* внутри воспринимается как обычный символ;
3. Синтаксис однострочных и блочных комментариев в C# полностью повторяет поведение C/C++;
4. Правила написания комментариев: не дублируйте то, что буквально делает код, описывайте бизнес-задачу и логику проектирования для удобства поддержки в будущем. Комментарии, повторяющие только имена переменных, не несут полезной информации.
5. Краткие пояснения, временное отключение одной строки кода → используйте //
6. Массовое комментирование нескольких строк, частичное скрытие фрагмента внутри строки → используйте /* */
7. Описание интерфейсов классов/методов, автоматическая генерация документации проекта → используйте ///

* Генерация документации

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

Настройка в Visual Studio

1. Правый клик по проекту → Свойства → вкладка Сборка (Build);
2. Отметьте галочкой пункт: Generate XML documentation file (Создать файл XML-документации);
3. Путь вывода по умолчанию: bin\Debug\ИмяПроекта.xml, можно задать собственный путь;
4. Примените настройку для All Configurations (Все конфигурации), чтобы XML генерировался как для Debug, так и для Release;
5. Перестройте проект, в целевом каталоге появится полный XML-файл с комментариями.

Конфигурация через .NET CLI (без Visual Studio)

Откройте файл проекта .csproj и добавьте следующий узел:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
Code language: HTML, XML (xml)

Выполните команду сборки:

dotnet build

Назначение XML-файла

В этом XML-файле хранятся все комментарии с тегами <summary>、<param>、<returns> — это исходные данные для генерации справочной документации. Также Visual Studio считывает этот файл и отображает комментарии во всплывающих подсказках IntelliSense.

Другие инструменты для генерации документации

Официальный инструмент Microsoft DocFX (рекомендован корпорацией, создаёт статические сайты документации на HTML)

Sandcastle (устаревший инструмент Microsoft для создания офлайн-файлов справки CHM)

Лёгкие сторонние утилиты (например Doxygen)

Описаны три типа синтаксиса комментариев