Комментарии
41C# --- Руководство по C# --- Комментарии
Комментарии являются немаловажной частью любого языка программирования, т.к. позволяют удобно пояснять различные участки кода. В C# используются традиционные комментарии в стиле С — однострочные (//...) и многострочные (/* . . . */):
// Это однострочный комментарий
/* Это уже
многострочный комментарий */
Все, что находится в однострочном комментарии — от // до конца строки — игнорируется компилятором, как и весь многострочный комментарий, расположенный между /* и */. Очевидно, что в многострочном комментарии не может присутствовать комбинация */, поскольку она будет трактоваться как конец комментария.
Многострочный комментарий можно помещать в одну строку кода:
Console.WriteLine (/* Здесь идет комментарий! */ "Это скомпилируется");
Встроенные комментарии вроде этого нужно применять осторожно, потому что они могут ухудшить читабельность кода. Однако они удобны при отладке, скажем, когда необходимо временно попробовать запустить программу с указанным другим значением:
DoSomethingMethod (Width, /*Height*/ 100);
Символы комментария, включенные в строковый литерал, конечно же, трактуются как обычные символы:
string s = "/* Это просто нормальная строка */";
Документация XML
В дополнение к комментариям в стиле C, проиллюстрированным выше, в C# имеется очень искусное средство, на которое я хочу обратить особое внимание: способность генерировать документацию в формате XML на основе специальных комментариев. Это однострочные комментарии, начинающиеся с трех слешей (///) вместо двух. В таких комментариях можно размещать XML-дескрипторы, содержащие документацию по типам и членам типов, используемым в коде.
XML-дескрипторы, распознаваемые компилятором, перечислены в следующей таблице:
Дескриптор | Описание |
---|---|
<c> | Помечает текст в строке как код |
<code> | Помечает множество строк как код |
<example> | Помечает пример кода |
<exception> | Документирует класс исключения (синтаксис проверяется компилятором) |
<include> | Включает комментарии из другого файла документации (синтаксис проверяется компилятором) |
<list> | Вставляет список в документацию |
<param> | Помечает параметр метода (синтаксис проверяется компилятором) |
<paramref> | Указывает, что слово является параметром метода (синтаксис проверяется компилятором) |
<permission> | Документирует доступ к члену (синтаксис проверяется компилятором) |
<remarks> | Добавляет описание члена |
<returns> | Документирует возвращаемое методом значение |
<see> | Представляет перекрестную ссылку на другой параметр (синтаксис проверяется компилятором) |
<seealso> | Представляет раздел "see also" ("смотреть также") в описании (синтаксис проверяется компилятором) |
<summary> | Представляет краткий итог о типе или члене |
<value> | Описывает свойство |
Чтобы увидеть, как это работает, рассмотрим пример кода, в который добавим некоторые 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:) или членом (М:).