Programming: C#

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

Комментирование блока текста

Чтобы вставить блочный (многострочный комментарий), текст комментария обрамляется /* */:

/* Эта переменная хранит количество элементов */
int count;
    

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

Также можно закомментировать строку текста (всю или часть). Для этого начало комментария отмечается текстом //:

int count;  // Эта переменная хранит количество элементов
    

XML документирование кода C#

       Как уже говорили, третим способом комментирования является XML документирование вашего C# кода. Если вы уже ознакомились с опциями компилятора C#, то наверняка отметили наличие параметра "/doc". Используя его, вы можете получить из исходного файла C#, XML файл, описывающий его. Полученный файл вы можете обрабатывать как хотите, например, преобразовав в HTML-документацию с помощью специальной . Конечно же, сущeствуют правила документирования кода. О них то мы и будем говорить далее...

<c>

Тэг <c> указывает на то, что текст, заключенный в него, является кодом.

<code>

Тэг <code> имеет тоже самое значение, что и тэг <c>, но используется для маркировки нескольких строк.

<example>

Тэг <example> используется для указания примера использования какого-либо метода или иного элемента вашего модуля.

<exception>

Тэг <exception> используется для комментирования исключений в вашем коде. Для этого параметр тэга cref="..." должен содержать System.Exception. Компилятор проверит существует ли исключение, и в случае отсутствия выдаст ошибку. В следующем примере демонстрируется использование этого тэга:

/// <exception cref="System.Exception"> Это исключение </exception>
class SampleClass : Exception {     }

Результат обработки тэга <exception> таков: В XML файле, в тэге <member name="T:SampleClass">, соответствующем элементу вашего кода, будет находиться тэг <exception>, с параметром cref, указывающим каноническое имя элемента. Внутри этого тэга будет находиться ваш комментарий. Например таким будет результат компилирования последнего примера:

<?xml version="1.0"?>
<doc>
    <members>
        <member name="T:SampleClass">
            <exception cref="T:System.Exception"> Это исключение </exception>
        </member>
    </members>
</doc>
    

<list>

Тэг <list> используется для создания таблицы, ненумерованного, нумерованного списка или списка определений. У него есть параметр type, который может принимать три значения: "bullet" - для ненумерованного списка, "number" - для нумерованного списка и "table" - для таблицы.

Внутри <list> могут находиться два вида тэгов: <listheader> и <item>. Каждый из них может содержать внутри себя два тэга - <term> и <description>.

<listheader> используется для описания заголовка таблицы или списка, тэг <item> для указания элемента. В случае таблицы, нумерованных или ненумерованных списков внутри тэгов <listheader> и <item> используется только тэг <term>, в случае списка определений <term> и <description>.

Следующий пример демонстрирует использование <term> для создания списка определений:

public class SampleClass {
/// <list type="bullet">
/// <listheader>
/// <term> Фрукты </term>
/// </listheader>
/// <item>
/// <term> Яблоко </term>
/// <description> растет на яблоне </description>
/// </item>
/// <item>
/// <term> Банан </term>
/// <description> растет на пальме </description>
/// </item>
/// <item>
/// <term> Груша </term>
/// <description> растет на груше </description>
/// </item>
/// </list>
public static void Main () {   }
    }

<para>

Тэг <para> используется для обозначения параграфа. Его следует использовать внутри таких тэгов, как <return> и <remark>.

<param>

Тэг <param> используется для описания агрументов методов. Его параметр name содержит имя аргуметна метода, в сам же тэг заключено описание агрумента.

public class SampleClass {
/// <param name="input"> Содержит строку ввода </param>
public static void SampleMethod (String input) {   }
    

<paramref>

Тэг <paramref> показывает, что слово является аргументом метода. Его параметр name содержит имя аргуметна метода. Его использование показано в следующем примере:

public class SampleClass {
/// <paramref name="input"/> - это строка ввода.
public static void SampleMethod (String input) {   }
    

<permission>

Тэг <permission> используется для комментирования прав доступа к элементам вашего кода. Для этого параметр тэга cref="..." должен содержать System.Security.PermissionSet. В следующем примере демонстрируется использование этого тэга:

using System;
class SampleClass{
/// <exception cref="System.Security.PermissionSet">
/// Свободный доступ к этому методу </exception>
public static void SampleMethod() {   }
public static void Main() {    }
    

Результат обработки этого примера показан ниже:

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:SampleClass.SampleMethod">
            <permission cref="T:System.Security.PermissionSet">
			 Свободный доступ к этому методу </permission>
        </member>
    </members>
</doc>
    

<remarks>

Тэг <remarks> служит для вставки комментариев для вашего класса или другого типа.

<returns>

Тэг <returns> используется для описания возвращаемого значения метода. Следующий пример демонстрирует его использование:

using System;
class SampleClass{
/// <returns> Возвращает число Пи </returns>
public static double PiSample() { return 3.1415926; }
public static void Main() {    }

<see>

Тэг <see> позволяет вам ссылаться на любой элемент, доступный в процессе компиляции, например элемент вашего кода. Его параметр cref="..." - ссылка на этот элемент. Пример:

using System;
class SampleClass{
/// <para> Метод Main использует System.Console. 
/// <see cref="System.Console"/> for console operations. </para>
public static void Main() {    
System.Console.WriteLine("SampleClass Console Output");
}
    

<seealso>

Тэг <seealso> ссылается на элементы, которые следует поместить в раздел "смотри также". Парамент этого тэга cref="..." - ссылка на любой элемент доступный в процессе компиляции.

<summary>

Тэг <summary> следует использовать для описания элемента вашего класса. Для описания самого класса следует использовать <remarks>. Пример:

using System;
/// <remarks> Это мой класс </remarks>
class SampleClass{
/// <summary> Main это метод класса SampleClass </summary>
public static void Main() {       }
    

<value>

Тэг <value> используется для описания property.

       Как вы уже могли заметить, xml комментарий кода начинается с "///". Помимо того, компилятор проверяет синтаксис всех тэгов, и допустимость употребения большинства тэгов. Например, если вы захотите описать несуществующий агрумент метода, компилятор выдаст ошибку.

       Вам могло показаться, что некоторые тэги являются бессмысленными, без них можно обойтись. Необходимо отметить, что xml не несет в себе представления, а правильная структура ваших xml комментариев гарантирует правильное их представление. Именно поэтому мы советуем вам, использовать приведенные выше рекомендации к использованию.
Мы создали одно из html представлений xml-файлов документации. Также мы предлагаем вам (с исходным кодом на C#), которая будет создавать html файл, используя xml-файл, созданный компилятором C#, и его xsl представление.

       В получаемом нами xml файле, все элементы кода имеют некоторые правила представления. Во-первых, при упоминании элемента кода, используется полное иерархическое представление пространств имен. Например, если вы использовали using System и тип String, то его представление в xml будет иметь вид System.String. Точнее T:System.String. Перед каждым элементом кода в xml, ставится модификатор, говорящий о том, чем является этот элемент. Ниже приведена таблица модификаторов:

Назад | Вперёд