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

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

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

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

Комментарии используются для документирования кода. В следующем примере компилятор принимает комментарий:

/* Comments can contain keywords such as for and while without generating errors. */ 

Комментарии в коде могут находиться в той же строке, что и оператор:

printf( "Hello\n" ); /* Comments can go here */ 

Перед функциями или программными модулями можно вставлять блоки комментариев с описаниями.

/* MATHERR.C illustrates writing an error routine * for math functions. */ 

Так как комментарии не могут содержать вложенные комментарии, в этом примере возникает ошибка:

/* Comment out this routine for testing /* Open file */ fh = _open( "myfile.c", _O_RDONLY ); . . . */ 

Причина ошибки в том, что компилятор распознает первое сочетание символов, */ , расположенное после слов Open file , как конец комментария. Он пытается обработать оставшийся текст, а обнаружив символы */ за пределами комментария, выдает сообщение об ошибке.

Хотя с помощью комментариев можно скрывать часть кода для тестирования, для этого есть полезная альтернатива: директивы препроцессора #if и #endif и условная компиляция. Дополнительные сведения см. в статье Preprocessor Directives (Директивы препроцессора) в справочника по препроцессору.

Блок, относящийся только к системам Microsoft

Компилятор Microsoft также поддерживает однострочные комментарии, перед которыми ставятся две косые черты ( // ). Эти примечания не могут быть расширены до второй строки.

// This is a valid comment 

Комментарии, начинающиеся с двух косых черт ( // ), заканчиваются следующим символом новой строки, которому не предшествует escape-символ. В следующем примере символу новой строки предшествует обратная косая черта ( \ ), создается escape-последовательность. Эта escape-последовательность заставляет компилятор обрабатывать следующую строку как часть предыдущей строки. Дополнительные сведения см. в статье Escape Sequences (Escape-последовательности).

// my comment \ i++; 

Поэтому оператор i++; скрыт комментарием.

В Microsoft C расширения Microsoft по умолчанию включены. Отключить их можно при помощи параметра /Za.

Завершение блока, относящегося только к системам Майкрософт

Комментарии (C++)

Комментарий — это текст, который предназначен для программистов и не обрабатывается компилятором. Обычно комментарии используются для создания заметок к коду для дальнейшего использования. Компилятор обрабатывает их как пробел. При тестировании можно использовать примечания, чтобы сделать определенные строки кода неактивными; Однако директивы препроцессора лучше работают для этого, #if / #endif так как вы можете окружать код, содержащий комментарии, но не вложенные примечания.

Комментарии в C++ записываются одним из следующих способов:

• Символы /* (косая черта и звездочка), за которыми следует любая последовательность символов, включая переводы строки, после чего ставятся символы */ . Это тот же синтаксис, который используется в ANSI C.
• Символы // (две косые черты), за которыми следует любая последовательность символов. Символ перевода строки, непосредственно перед которым нет обратной косой черты, завершает комментарий, оформленный таким способом. Поэтому такие комментарии часто называют однострочными.

Символы, используемые для оформления комментариев ( /* , */ и // ), не имеют специального значения внутри символьной константы, строкового литерала, или комментария. Однако вложение комментариев, оформленных первым способом, не допускается.

Комментарии

В С все комментарии начинаются с пары символов /* и заканчиваются парой */. Между слэшем и звездочкой не должно быть пробелов. Компилятор игнорирует любой текст между данными па­рами символов. Например, следующая программа выводит на экран только hello:

#include
int main(void)
printf(«hello»);
/* printf(«there»); */
return 0;
>

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

х = 10 + /* сложение чисел */ 5;
в то время как
swi//* не работает */tch(c) < . . .

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

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

/* внешний комментарий
х = у / а;
/* внутренний комментарий вызывает ошибку */
*/

Комментарии следует использовать, когда необходимо объяснить какую-либо операцию кода. Все функции, за исключением самых очевидных, должны содержать комментарии в начале их объяв­ления, где следует писать, что функция делает, какие параметры она получает и что возвращает.

ЗАМЕТКА: С++ полностью поддерживает С-стиль комментариев. Тем не ме­нее он также позволяет определять однострочные комментарии. Однострочный комментарий начинается с // и заканчивается в конце строки.

Комментарии

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

// Это однострочный комментарий /* Это уже многострочный комментарий */

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

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

Console.WriteLine (/* Здесь идет комментарий! */ "Это скомпилируется");

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

DoSomethingMethod (Width, /*Height*/ 100);

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

string s = "/* Это просто нормальная строка */";

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

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

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

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

Дескриптор	Описание
	Помечает текст в строке как код
	Помечает множество строк как код
	Помечает пример кода
	Документирует класс исключения (синтаксис проверяется компилятором)
	Включает комментарии из другого файла документации (синтаксис проверяется компилятором)
	Вставляет список в документацию
	Помечает параметр метода (синтаксис проверяется компилятором)
	Указывает, что слово является параметром метода (синтаксис проверяется компилятором)
	Документирует доступ к члену (синтаксис проверяется компилятором)
	Добавляет описание члена
	Документирует возвращаемое методом значение
	Представляет перекрестную ссылку на другой параметр (синтаксис проверяется компилятором)
	Представляет раздел «see also» («смотреть также») в описании (синтаксис проверяется компилятором)
	Представляет краткий итог о типе или члене
	Описывает свойство

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

using System; using System.Collections.Generic; using System.Linq; using System.Text; namespace ConsoleApplication1 < /// 
/// Класс Program /// основной класс программы /// выводящий текст "Hello, World!" ///
 class Program < /// 
/// Метод Main() является /// входной точкой работы программы ///
 /// Аргумент метода Main() 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 со следующим содержимым:

   Program    
Класс Program основной класс программы выводящий текст "Hello, World!"
   
Метод Main() является входной точкой работы программы
 Аргумент метода Main()    

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