Комментарии в C#

В этой статье вы узнаете о комментариях в C#, их разных типах, а также о том, зачем и как их использовать в программе.

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

В C# есть 3 типа комментариев:

• однострочные комментарии (//);
• многострочные комментарии (/* */);
• комментарии XML (///).

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

Однострочные комментарии в C# начинаются с двух слешей: //. Компилятор игнорирует все слова, начиная с // и заканчивая концом строки.

int a = 5 + 7; // Прибавляем 7 к 5

«Прибавляем 7 к 5» — это комментарий.

Пример 1. Используем однострочный комментарий

// Программа «Привет, мир!»  
using System;

namespace HelloWorld
{
    class Program
    {
        public static void Main(string[] args)  // Выполнение начинается с метода Main
        {
            // Выводит на экран сообщение «Привет, мир!»  
            Console.WriteLine("Привет, мир!");
        }
    }
}

В программе выше 3 однострочных комментария:

1. Программа «Привет, мир!»; 
2. Выполнение начинается с метода Main;
3. Выводит на экран сообщение «Привет, мир!».

Однострочные комментарии можно записывать в отдельной строке или в одной строке с кодом. Лучше — в отдельной строке, таковы рекомендации по написанию кода на C#.

Пример 2. Используем многострочные комментарии

/*
    Это программа «Привет, мир!» на C#.
    Она выводит на экран сообщение «Привет, мир!».
*/
using System;

namespace HelloWorld
{
    class Program
    {
        public static void Main(string[] args)
        {
            /* Выводит на экран сообщение «Привет, мир!» */
            Console.WriteLine("Привет, мир!");
        }
    }
}

В программе выше 2 многострочных комментария: 

/*
Это программа «Привет, мир!» на C#.
Она выводит на экран сообщение «Привет, мир!».
*/

 

и

/* Выводит на экран сообщение «Привет, мир!» */

Возможно, вы заметили, что многострочный комментарий необязательно должен занимать несколько строк. /* … */ можно использовать вместо однострочных комментариев.

Комментарии документации XML

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

О XML можно почитать в этой статье.

/// <summary>
///  Это тоже программа «Привет, мир!» 
/// </summary>

using System;

namespace HelloWorld
{
    class Program
    {
        public static void Main(string[] args)
        {
            Console.WriteLine("Привет, мир!");
        }
    }
}

Вот XML-комментарий в программе выше:

/// <summary>
/// Это тоже программа «Привет, мир!» 
/// </summary>

Сгенерированная XML-документация (файл с расширением .xml) будет выглядеть вот так:

<?xml version="1.0"?>
<doc>
	<assembly>
		<name>HelloWorld</name>
	</assembly>
	<members>
	</members>
</doc>

Подробнее о XML-документации можно узнать в руководстве от Microsoft. 

Как правильно пользоваться комментариями

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

Например, здесь комментарий лишний:

// Выводит Hello World
Console.WriteLine ("Привет, мир!");

И без него очевидно, что напечатается сообщение «Привет, мир!». В таких случаях комментариев лучше избегать. 

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