Что такое комментарий в программировании

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

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

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

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

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

Комментарии

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

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

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

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

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

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

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

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

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

Комментарии (программирование)

Коммента́рии — пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии — часть текста программы, не влияющая на её семантику. Комментарии не оказывают никакого влияния на результат компиляции программы или её интерпретацию. Помимо исходных текстов программ, комментарии также применяются в языках разметки и языках описания.

Назначение комментариев

Большинство специалистов сходятся во мнении, что комментарии должны объяснять намерения программиста, а не код; то, что можно выразить на языке программирования, не должно выноситься в комментарии — в частности, надо использовать говорящие названия переменных, функций, классов, методов и пр., разбивать программу на лёгкие для понимания части, стремиться к тому, чтобы структура классов и структура баз данных были максимально понятными и прозрачными и т. д. Есть даже мнение (его придерживаются в экстремальном программировании и некоторых других гибких методологиях программирования), что если для понимания программы требуются комментарии — значит, она плохо написана.

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

Комментарии часто используются для временного отключения части кода. В языках C и C++, некоторые рекомендуют использовать с той же целью директивы препроцессора ( #if 0 … #endif ).

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

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

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

Аннотации

Другой вид комментариев — аннотации — применяется в набросках доказательств правильности программ. Такие комментарии описывают состояние компьютера, когда программа в процессе выполнения достигнет точки, где расположен комментарий. Программа, снабжённая комментариями-аннотациями, называется аннотированной программой.

Автоматическая генерация документации

Основная статья: Генератор документации

Специальным образом оформленные комментарии (т. н. документирующие комментарии) используются для автоматического создания документации, в первую очередь, к библиотекам функций или классов. Для этого используются генераторы документации, например, такие как javadoc [1] для языка Java, phpDocumentor для PHP [2] , doxygen [3] для C и C++ и др.

Документирующие комментарии как правило оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.

/** * Имя или краткое описание объекта * * Развернутое описание * * @имя_дескриптора значение * @return тип_данных */ 

В некоторых средах программирования (например, Eclipse, NetBeans, Python, Visual Studio) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций.

Трансляция программ

Во время трансляции комментарии распознаются на стадии лексического анализа (и, соответственно, считаются лексемами). Распознавание на стадии препроцессирования накладно и даже чревато ошибками; включение комментариев в синтаксические диаграммы практически невозможно.

В различных языках и средах программирования

• Ассемблер

• Форт

• BASIC

• BLITZ PLUS

• BAT-файлы и команды DOS

• пакетный файлLinux, QNX

• C, C++, PHP, C#, Java и JavaScript

• Кобол

• Delphi (Object Pascal)

• Fortran

• HTML, XML, XHTML, wiki-разметка

• Конфигурационные (ini) файлы

• Файлы реестра Windows (REG)

• Система аналитических вычислений Mathematica

• Система аналитических вычислений Maple

• Pascal, Modula-2, Modula-3, Oberon и ML

• Perl

• Python, различные варианты командных оболочек UNIX, AWK, sed, Tcl

• PL/SQL

• Ruby

• Smalltalk

• TeX, LaTeX, PostScript

• Visual Basic

• Lua

Специальные комментарии

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

Например в диалекте Турбо Паскаль псевдокомментарии и используются для отключения и включения стандартного контроля ошибок ввода-вывода. Похожие специальные комментарии используются в языке разметки HTML для указания типа SGML-документа, «экранирования» таблиц стилей и сценариев на языках JavaScript и VBScript:

Некоторые комментарии программисты используют в ходе своей работы. Подобные комментарии особенно полезны, когда над одним кодом работает несколько разработчиков. Так, комментарием TODO обычно помечают участок кода, который программист оставляет незавершённым, чтобы вернуться к нему позже. Комментарий FIXME помечает обнаруженную ошибку, которую решают исправить позже. Комментарий XXX обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.

Примечания

См. также

• Условный комментарий
• Документирующие комментарии

• Концепции языков программирования

Что такое комментарии и зачем они нужны?

Возможно вы заметили, что в листингах из примеров встречается не только код программ, но и мои пояснения написанные после «//». Это комментарии . Они предназначены для того, чтобы пояснять какую-нибудь сложную и непонятную часть вашей программы. Кроме того, иногда их используют, чтобы на время отключить какую-то часть кода. Это возможно потому, что всё что записано в комментарии компилятор игнорирует. Если быть точнее то к тому времени, как компилятор начнёт обрабатывать код программы все комментарии будут уже удалены. Поэтому туда можно писать всё что угодно.

Рис.1. Пример использования комментария в программе. (Язык Fortran)

В языке Си есть два вида комментариев. Первый вид тот, который я использую в коде. Такой комментарий называет однострочным. Он действует с того момента как появился и до конца текущей строки. Есть ещё и многострочный комментарий. Начало такого комментария обозначается последовательностью «/*», а конец — «*/». Всё, что будет записано между этими двумя последовательностями символов не будет восприниматься компилятором. Обычно многострочные комментарии используют для описания больших кусков кода, очень сложных для понимания функций, для указания авторства, для исключения большого куска кода из программы и т.д.

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

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

Комментарии в коде могут быть как очень смешными:

// Магия. Не трогать. //Этот код отстой, и мы оба это знаем. //Так что двигайся дальше, а идиотом ты назовешь меня потом. // Дорогой я_из_будущего! Пожалуйста, прости меня за этот код. // Если я еще раз увижу такое, мне придется начать носить на работу оружие. /* Если это условие когда-нибудь выполнится, пожалуйста, сообщите мне по тел. ххх-ххх-ххх за вознаграждение. */ // пьян, исправить позже // Когда я начинал это писать, только Бог и я понимали, что я делаю // Сейчас остался только Бог

//Пожалуйста, работай // Я не несу ответственности за этот код. // Они меня заставили написать его против моей воли. /* Если вы читаете эти строки, значит вам поручили мой предыдущий проект. Я очень, очень сочувствую вам. Удачи. */

Сохрани в закладки или поддержи проект.

Практика

1. Откройте программу «Hello, World». Попробуйте закомментировать строчку printf(«Hello, World!\n»); Как вы думаете, как изменится работа программы? Проверьте свое предположение, скомпилировав и запустив эту программу.
2. Закомментируйте в следующей программе некоторые строки так, чтобы на экране появился следующий текст:

The Matrix has you.

Follow the white rabbit.

Программа для изменения

#include int main (void) < while (1 >0) < printf("Wake up, Neo. \n\n"); >if (0 > 1) < printf("The Matrix has you. \n\n"); >printf("Follow the white rabbit. \n"); return 0; >

Не бойтесь новый непонятных команд! С ними мы ещё разберёмся. =) Программистам часто приходится работать с кодом, в котором они не всё до конца понимают.

#include #include //библиотека с локализацией, чтобы были доступны русские буквы int main(void) < setlocale(LC_ALL, ""); //подключаем локализацию // char str1[]= "Поздравляю! Вы справились с задачей!"; // for (int i=0; i

Дополнительные материалы

• Подборки смешных и не очень комментариев: раз, два.
  Увидели смешной комментарий? Напишите его в комменты.
• Немного о том, как и для чего [не]нужно писать комментарии