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

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

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

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

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

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

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

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

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

Дескриптор	Описание
<c>	Помечает текст в строке как код
<code>	Помечает множество строк как код
<example>	Помечает пример кода
<exception>	Документирует класс исключения (синтаксис проверяется компилятором)
<include>	Включает комментарии из другого файла документации (синтаксис проверяется компилятором)
<list>	Вставляет список в документацию
<param>	Помечает параметр метода (синтаксис проверяется компилятором)
<paramref>	Указывает, что слово является параметром метода (синтаксис проверяется компилятором)
<permission>	Документирует доступ к члену (синтаксис проверяется компилятором)
<remarks>	Добавляет описание члена
<returns>	Документирует возвращаемое методом значение
<see>	Представляет перекрестную ссылку на другой параметр (синтаксис проверяется компилятором)
<seealso>	Представляет раздел «see also» («смотреть также») в описании (синтаксис проверяется компилятором)
<summary>	Представляет краткий итог о типе или члене
<value>	Описывает свойство

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

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

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

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

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

Комментарии в языке C#

Только в простейшем случае исходная программа может состоять из одного файла, гораздо чаще приходится иметь дело с несколькими файлами – программными модулями (см. примеры консольного и оконного приложений).

Комментариями называются те части программных модулей, которые при компиляции игнорируются.

Зачем же тогда даже опытные программисты вставляют их в тексты своих программ?

Первая причина – сохранение выходных данных программы (наименование, назначение, версия, связь с другими модулями, авторские права, время создания или последнего изменения).

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

Третья причина – обеспечение понимания программы другими программистами – коллегами, руководителями и учениками.

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

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

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

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

Очевидно, что в многострочном комментарии не может присутствовать комбинация */, поскольку она будет трактоваться как конец комментария.
Многострочный комментарий можно помещать в одну строку кода:
Console.WriteLine (/* Здесь идет комментарий! */ «Это скомпилируется»);

Встроенные комментарии вроде этого нужно применять осторожно, потому что они могут ухудшить читабельность кода. Однако они удобны при отладке, скажем, когда необходимо временно попробовать запустить программу с указанным другим значением:
DoSomethingMethod (Width, /*Height*/ 100);
Символы комментария, включенные в строковый литерал (между кавычками), трактуются как обычные символы:
string s = «/* Это просто нормальная строка */»;

Пример комментирования (несколько избыточного) вашей первой программы:

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

NEW: Наш Чат, в котором вы можете обсудить любые вопросы, идеи, поделиться опытом или связаться с администраторами.

Комментарии в C#

В этой статье вы узнаете о комментариях в C#, их разных типах, а также о том, зачем и как их использовать в программе.

Комментарии помогают другим разработчикам или вам самим в будущем понять тот или иной фрагмент кода. Это понятные предложения, которые описывают, как работает фрагмент и зачем он нужен. Компилятор комментарии полностью игнорирует, они нужны только человеку.

В C# есть 3 типа комментариев:

однострочные комментарии ( // );
многострочные комментарии ( /* */ );
комментарии XML ( /// ).

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

Однострочные комментарии в C# начинаются с двух слешей: // . Компилятор игнорирует все слова, начиная с // и заканчивая концом строки.

«Прибавляем 7 к 5» — это комментарий.

Пример 1. Используем однострочный комментарий

В программе выше 3 однострочных комментария:

Программа «Привет, мир!» ;
Выполнение начинается с метода Main ;
Выводит на экран сообщение «Привет, мир!» .

Однострочные комментарии можно записывать в отдельной строке или в одной строке с кодом. Лучше — в отдельной строке, таковы рекомендации по написанию кода на C#.

Пример 2. Используем многострочные комментарии

В программе выше 2 многострочных комментария:

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

Комментарии документации XML

Комментарии к документации XML — это особая фича C#. Они начинаются с тройной косой черты `///` и используются для описания фрагмента кода с помощью XML-тегов. Из таких комментариев позже создают отдельные файлы документации XML.

О XML можно почитать в этой статье.

Вот XML-комментарий в программе выше:

Сгенерированная XML-документация (файл с расширением .xml) будет выглядеть вот так:

Подробнее о XML-документации можно узнать в руководстве от Microsoft.

Как правильно пользоваться комментариями

Комментарии нужны, чтобы объяснять части кода, но злоупотреблять ими не нужно.

Например, здесь комментарий лишний:

И без него очевидно, что напечатается сообщение «Привет, мир!». В таких случаях комментариев лучше избегать.