Обучение C#

Формула программиста
основатель — Волосатов Евгений Витольдович

Комментарии

Многострочные комментарии

В языке C# при составлении программы используются символы комментариев:
/* - начало комментария
*/ - конец комментария

Вся последовательность символов, заключенная между символами начала и конца комментария, является комментарием. Такие комментарии могут занимать несколько строк.

 
 
int i; /* переменная i
будет использоваться как параметр цикла */

Многострочные комментарии удобно использовать при отладке, когда нужно временно не выполнять часть кода программы с целью найти ошибку.

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

Язык C# также поддерживает написание коротких (однострочных) комментариев. Для этого используются символы //. В этом случае комментарием является все, что расположено после символов // и до конца строки. Текст следующей строки считается кодом программы.
 
 
int i; // параметр внешнего цикла
int j; // параметр внутреннего цикла

XML-комментарии

Среда разработки Microsoft Visual Studio позволяет создавать документацию для кода программ путем включения XML-элементов в специальные поля комментариев. Такие комментарии начинаются с тройного символа слеша /// и располагаются непосредственно перед блоком кода, к которому они относятся. Каждая новая строка XML-комментариев начинается с символов ///.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
using System;
namespace MyProgram
{
  class Program
  {
    /// <summary>
    /// Функция вывода на экран сообщения
    /// </summary>
    /// <param name="s">Строка сообщения</param>
    static void print(string s)
    {
      Console.WriteLine(s);
    }
    /// <summary>
    /// Основная функция
    /// </summary>
    /// <param name="args"></param>
    static void Main(string[] args)
    {
      Console.Title = "XML-комментарии";
      print("Hello");
      Console.ReadKey();
    }
  }
}
image articles/528/528_1.png
При этом при использовании функции print() автоматически высвечивается описание этой функции и ее аргументов.
image articles/528/528_2.png
При составлении XML-комментариев можно использовать следующие XML-теги.
  • <c> - содержит текст, который нужно представить как код.
  • <code> - помечает несколько строк как код.
  • <example> - содержит описание примера кода, может содержать вложенный тег <code>.
  • <exception> - служит для указания исключений, содержит параметр
    <exception cref="member">Описание исключения</exception>,
    который указывает ссылку на исключение.
  • <include> - используется для ссылок на комментарии в других файлах
    <include file='filename' path='tagpath[@name="id"]' />
    • filename - имя файла XML, содержащего документацию, заключенное в одинарные кавычки (' ');
    • path - путь тегов в filename, заключенный в одинарные кавычки (' '), который приводит к тегу name;
    • name - спецификатор имени в теге, который предшествует комментариям; name будет иметь id;
    • id - идентификатор для тега, который предшествует комментариям, заключенный в двойные кавычки (" ").
  • <list> - вставляет список в документацию.
  • <para> - используется внутри тегов <summary>, <remarks>, <returns> и позволяет структурировать текст.
  • <param> - используется в комментариях объявления метода для описания его параметров со следующим синтаксисом:
    <param name="Имя">Описание</param>
    name - имя параметра
  • <paramref> - позволяет указать, что слово в комментариях кода, например в блоке <summary> или <remarks>, ссылается на параметр:
    <paramref name="Имя"/>
  • <permission> - позволяет документу получить доступ к члену
    <permission cref="Ссылка">Описание</permission>
  • <remarks> - используется для добавления сведений о типе, дополняющих сведения, указанные в <summary>
    <remarks>Описание</remarks>
  • <returns> - используется в комментариях объявления метода для описания возвращаемого значения:
    <returns>Описание</returns>
  • <see> - позволяет указать ссылку из текста:
    <see cref="Ссылка"/>
  • <seealso> - позволяет указать текст, который будет отображаться в разделе "См. также":
    <seealso cref="Ссылка"/>
  • <summary> - используется для описания назначения блока, которому он предшествует:
    <summary>Описание</summary>
  • <typeparam> - используется в комментарии объявления универсального типа или метода для описания параметра типа:
    <typeparam name="Имя">Описание</typeparam>
  • <typeparamref> - содержит дополнительные сведения параметрах типа в универсальных типах и методах, использование этого тега позволит пользователям файла документации придать слову определенный формат, например выделить его курсивом:
    <typeparamref name="Имя"/>
  • <value> - позволяет описывать представляемое свойством значение:
    <value>Описание</value>
Чтобы обработать и сохранить комментарии документации в файл, при компиляции необходимо использовать параметр /doc.
Для этого переходим по правой кнопке мыши в меню Свойства проекта ⇒ Сборка и устанавливаем галочку напротив XML-файл документации.
image articles/528/528_3.png
При этом в указанной папке генерируется файл XML-документации примерно такого вида:
image articles/528/528_4.png

Сворачивание участков кода

Среда разработки Microsoft Visual Studio позволяет сворачивать блоки кода, ограниченные фигурными скобками. Эта возможность применима к описанию структур, классов, функций и методов и т. п.
Однако язык C# предусматривает директиву, позволяющую сворачивать участки кода. Это — директива #region. В конце блока сворачиваемого блока кода, обозначенного директивой #region, должна присутствовать директива #endregion:
 
 
 
#region Описание
...
#endregion

image articles/528/528_5.png
image articles/528/528_6.png


Автор: Вставская Елена Владимировна

 
Написать комментарий:




Начинаем практику по языку C#




Чтобы стать хорошим программистом — нужно писать программы. На нашем сайте очень много практических упражнений.

После заполнения формы ты будешь подписан на рассылку «C# Вебинары и Видеоуроки», у тебя появится доступ к видеоурокам и консольным задачам.

Несколько раз в неделю тебе будут приходить письма — приглашения на вебинары, информация об акциях и скидках, полезная информация по C#.

Ты в любой момент сможешь отписаться от рассылки.