Документирование исходного кода

Язык C# позволяет при написании программы снабжать исходный код особыми документирующими комментариями. Содержимое документирующих комментариев может затем быть выделено и обработано. Так реализуется концепция, при которой сам исходный код содержит необходимую документацию, описывающую его.

Рассмотрим общие принципы документирования кода. Документирующие комментарии – это либо однострочные комментарии, начинающиеся с последовательности ///, либо блочные комментарии, начинающиеся с последовательности /**. Они могут располагаться в любом месте кода, но обычно их помещают перед описанием пользовательского типа или перед методом. Кроме собственно текста, комментарии могут содержать документирующие теги. Теги позволяют выделить некие особые составляющие комментария – например, имя метода, параметры, пример использования. Если в тексте комментария нужно использовать символы < и >, то они заменяются последовательностями &lt; и &gt;. В случае ссылок на универсальные шаблоны имя параметра-типа может быть записано в фигурных скобках { и }.

Таблица 6

Документирующие теги

Тег и синтаксис	Описание
<c>text</c> <code>content</code>	Позволяют вставить в комментарий текст, являющийся кодом. Второй тег применяется при необходимости вставить несколько строк кода
<example> description </example>	Помечает части комментария, являющиеся примером. Обычно данный тег включает тег <code>
<exception cref="member"> description </exception>	Показывает, какие исключения может сгенерировать метод. Атрибут cref указывает на существующий тип ИС
<para>content</para>	Используется для визуального оформления – выделяет параграф
<param name="name"> description </param>	Описывает параметр метода
<paramref name="name"/>	Указывает, что элемент комментария является не просто словом, а параметром метода
<remarks> description </remarks>	Содержит дополнительное описание
<returns> description </returns>	Описание возвращаемого значения метода
<see cref="member"/> <seealso cref="mem"/>	Устанавливают ссылки на существующий тип или элемент типа
<summary> description </summary>	Содержит основное описание типа или элемента типа
<typeparam name="name"> description </typeparam>	Позволяет указать описание generic-параметра
<value> property-description </value>	Используется для описания свойства

Ниже приведён фрагмент кода с документирующими комментариями.

/// <summary>

/// Starts the network device.

/// </summary>

/// <see cref="List{T}"/>

/// <param name="startTimeout">The start timeout.</param>

/// <param name="sessionId">The session id.</param>

public bool Start(int startTimeout, int sessionId) {... }

Чтобы выделить документирующие комментарии из исходного кода, можно откомпилировать программу с ключом /doc:file, где file – это имя XML-файла с комментариями. При работе в Visual Studio в свойствах проекта достаточно установить флаг Build | Output | Xml Documentation File.

Заметим, что существуют самостоятельные проекты, которые расширяют возможности встроенной системы документирования кода. Упомянем такие проекты как NDoc и Sandcastle. Также достаточно популярным является GhostDoc – дополнение к Visual Studio, облегчающее генерирование документирующих комментариев.

Литература

1. Албахари, Дж. C# 3.0. Справочник: Пер. с англ. / Дж. Албахари, Б. Албахари. – 3-е изд. – Спб.: БХВ-Петербург, 2009. – 944 с.: ил.

2. Рихтер, Дж. CLR via C#. Программирование на платформе Microsoft.NET Framework 4.0 на языке C# / Дж. Рихтер. – 3-е изд. – Спб.: Питер, 2012. – 928 с.: ил.

3. Троелсен, Э. Язык программирования C# 2010 и платформа.NET 4.0 / Э. Троелсен. – 5-е изд. – М.: ООО «И.Д. Вильямс», 2011. – 1392 с.: ил.

4. Хейлсберг, А. Язык программирования C#. Классика Computers Science. / А. Хейлсберг, М. Торгерсен, С. Вилтамут, П. Голд. – 4-е изд. – Спб.: Питер, 2012. – 784 с.: ил.

5. Цвалина, К. Инфраструктура программных проектов: соглашения, идиомы и шаблоны для многократно используемых библиотек.NET.: Пер. с англ. / К. Цвалина. – М.: ООО «И.Д. Вильямс», 2011. – 416 с.: ил.

[1] При записи целочисленных литералов не рекомендуется использовать суффикс l (строчная латинская буква L), так как его легко перепутать с единицей.

[2] В C# имеется директива using для импорта пространств имён. Следует различать директиву using и оператор using.

[3] Объявление int[,][] data задаёт двумерный массив, состоящий из одномерных массивов. Иными словами, спецификаторы размерностей читаются слева направо.

[4] В CLR есть модификатор доступа, соответствующий protected и internal. Но при помощи языка C# такой уровень доступа описать нельзя.

[5] Разделяемыми могут быть не только классы, но также структуры и интерфейсы.

[6] Для доступа к константе применяется синтаксис имя-класса.имя-константы.

[7] Индексаторы транслируются в методы с именами get_Item() и set_Item(). Изменить имена методов можно, используя атрибут [IndexerName].

[8] В отличие от языка C#, CLR позволяет создавать статические индексаторы.

[9] Язык C# допускает только методы расширения, свойств и индексаторов расширения не существует.

[10] Если класс содержит статический конструктор (возможно, пустой), компилятор C# генерирует код, выполняющий инициализацию статических полей класса непосредственно перед первым использованием класса. Без статического конструктора такая инициализация проводится в произвольный момент до использования класса.

[11] Формально, от object не наследуются типы-указатели, используемые в неуправляемом коде (например, int*), а также интерфейсы (но интерфейсы приводятся к object).

[12] Операция упаковки выполняется и в случае, когда переменной типа интерфейс присваивается переменная типа значения. Этот аспект будет разобран при рассмотрении интерфейсов.

[13] В отличие от классов, в структуре конструктор без параметров присутствует даже при объявлении пользовательского конструктора.

[14] И класс Stack<T>, и класс Dictionary<K, V> рассмотрены только как примеры. В.NET Framework уже имеются полноценные аналоги данных классов.

[15] Универсальные методы могут заменить перекрытие методов в пользовательском типе, если алгоритмы работы различных версий перекрытых методов не зависят от типов параметров.

[16] Делегаты относятся к неизменяемым типам. Поэтому методы Combine() и Remove() возвращают новые объекты-делегаты.

[17] Если аргументов несколько, скобки нужно указывать. Когда лямбда-оператор не имеет входных аргументов, указываются пустые скобки.

[18] Поведение, аналогичное событиям, можно получить, используя открытие поля делегатов. Ключевое слово event заставляет компилятор проверять, что описание и генерация события происходят в одном классе, и запрещает для события все операции, кроме += и -=.