Комментарии

Комментарии являются немаловажной частью любого языка программирования, т.к. позволяют удобно пояснять различные участки кода. В C# используются традиционные комментарии в стиле С — однострочные (//...) и многострочные (/* . . . */):

// Это однострочный комментарий
/* Это уже
многострочный комментарий */

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

Многострочный комментарий можно помещать в одну строку кода:

Console.WriteLine (/* Здесь идет комментарий! */ "Это скомпилируется");

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

DoSomethingMethod (Width, /*Height*/ 100);

Символы комментария, включенные в строковый литерал, конечно же, трактуются как обычные символы:

string s = "/* Это просто нормальная строка */";

Документация XML

В дополнение к комментариям в стиле C, проиллюстрированным выше, в C# имеется очень искусное средство, на которое я хочу обратить особое внимание: способность генерировать документацию в формате XML на основе специальных комментариев. Это однострочные комментарии, начинающиеся с трех слешей (///) вместо двух. В таких комментариях можно размещать XML-дескрипторы, содержащие документацию по типам и членам типов, используемым в коде.

XML-дескрипторы, распознаваемые компилятором, перечислены в следующей таблице:

XML-дескрипторы для комментариев

Чтобы увидеть, как это работает, рассмотрим пример кода, в который добавим некоторые XML-комментарии:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ConsoleApplication1
{
    /// <summary>
    ///  Класс Program
    ///  основной класс программы
    ///  выводящий текст "Hello, World!"
    /// </summary>
    class Program
    {
        /// <summary>
        /// Метод Main() является
        /// входной точкой работы программы
        /// </summary>
        /// <param name="args">Аргумент метода Main()</param>
        static void Main(string[] args)
        {
            // Форматируем шапку программы
            Console.BackgroundColor = ConsoleColor.Green;
            Console.ForegroundColor = ConsoleColor.Black;
            Console.WriteLine("********************");
            Console.WriteLine("**** Мой проект ****");
            Console.WriteLine("********************");
            // Основная программа
            Console.BackgroundColor = ConsoleColor.Black;
            Console.ForegroundColor = ConsoleColor.Green;
            Console.WriteLine();
            Console.WriteLine("Hello, World!");

            // Ожидание нажатия клавиши Enter перед завершением работы
            Console.ReadLine();
        }
    }
}

Компилятор C# может извлекать XML-элементы из специальных комментариев и использовать их для генерации файлов XML. Чтобы заставить компилятор сгенерировать XML-документацию для сборки, указывается опция /doc вместе с именем файла, который должен быть создан:

     csc /t:library /doc:MyApplication.xml MyApplication.cs

Данная команда сгенерирует файл XML по имени MyApplication.xml со следующим содержимым:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Program
    </assembly>
    <members>
        <member name="T:ConsoleApplication1.Program">
            <summary>
             Класс Program
             основной класс программы
             выводящий текст "Hello, World!"
            </summary>
        </member>
        <member name="M:ConsoleApplication1.Program.Main(System.String[])">
            <summary>
            Метод Main() является
            входной точкой работы программы
            </summary>
            <param name="args">Аргумент метода Main()</param>
        </member>
    </members>
</doc>

Обратите внимание на то, что компилятор на самом деле выполнил некоторую работу за вас: он создал элемент <assembly> и также добавил элементы <member> для каждого члена класса в этом файле. Каждый элемент <member> имеет атрибут name с полным именем члена, снабженным префиксом — буквой, который указывает на то, является он типом (Т:), полем (F:) или членом (М:).