Комментарии (программирование) — Википедия
У этого термина существуют и другие значения, см. Комментарий.Коммента́рии — пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии — часть текста программы, не влияющая на её семантику. Комментарии не оказывают никакого влияния на результат компиляции программы или её интерпретацию. Помимо исходных текстов программ, комментарии также применяются в языках разметки и языках описания.
Большинство специалистов сходятся во мнении, что комментарии должны объяснять намерения программиста, а не код; то, что можно выразить на языке программирования, не должно выноситься в комментарии — в частности, надо использовать говорящие названия переменных, функций, классов, методов и пр., разбивать программу на лёгкие для понимания части, стремиться к тому, чтобы структура классов и структура баз данных были максимально понятными и прозрачными и т. д. Есть даже мнение (его придерживаются в экстремальном программировании и некоторых других гибких методологиях программирования), что если для понимания программы требуются комментарии — значит, она плохо написана.
Концепция грамотного программирования настаивает на включение в текст программы настолько подробных и продуманных комментариев, чтобы она стала исходным текстом не только для исполняемого кода, но и для сопроводительной документации.
Комментарии часто используются для временного отключения части кода.
В языках C и C++, некоторые рекомендуют использовать с той же целью директивы препроцессора (#if 0 … #endif).
Однострочные и многострочные комментарии[править | править код]
С точки зрения синтаксиса, существуют два вида комментариев. Многострочный комментарий может иметь любую длину, он отмечается специальными символами в начале и конце (например,
Однострочный комментарий отмечается специальным символом в начале (например, //) и продолжается до конца строки. Обычно допускается вложение однострочных комментариев в другие, как одно- так и многострочные комментарии. Способы записи можно чередовать, с точки зрения семантики они одинаковы.
Другой вид комментариев — аннотации — применяется в набросках доказательств правильности программ. Такие комментарии описывают состояние компьютера, когда программа в процессе выполнения достигнет точки, где расположен комментарий. Программа, снабжённая комментариями-аннотациями, называется
Автоматическая генерация документации[править | править код]
Специальным образом оформленные комментарии (т. н. документирующие комментарии) используются для автоматического создания документации, в первую очередь, к библиотекам функций или классов. Для этого используются генераторы документации, например, такие как javadoc[1] для языка Java, phpDocumentor для PHP[2], doxygen[3] для C и C++ и др.
Документирующие комментарии как правило оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.
Пример документирующего комментария
/** * Имя или краткое описание объекта * * Развернутое описание * * @имя_дескриптора значение * @return тип_данных */
В некоторых средах программирования (например, Eclipse, NetBeans, Python, Visual Studio) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций.
Во время трансляции комментарии распознаются на стадии лексического анализа (и, соответственно, считаются лексемами). Распознавание на стадии препроцессирования накладно и даже чревато ошибками; включение комментариев в синтаксические диаграммы практически невозможно.
В различных языках и средах программирования[править | править код]
- 1С
//однострочный комментарий
- Ада
--однострочный комментарий
;однострочный комментарийCOMMENT +…Многострочный комментарий.+Строка с этим символом завершает комментарий, вместо плюса может быть другой символ.
'однострочный комментарий> — поддерживается не во всех диалектахREMоднострочный комментарий
;однострочный комментарий
- BAT-файлы и команды DOS
REMоднострочный комментарий::однострочный комментарий
#однострочный комментарий
/*многострочный комментарий*///однострочный комментарий#однострочный комментарий (для PHP)- Способ комментирования больших кусков кода в C/C++. Используется не для написания комментариев к программе, а для временного сокрытия части функциональности (в Java и JavaScript невозможен):
#if 0…кусок кода…#endif
* (на седьмой позиции)— однострочный комментарий
(* многострочный комментарий *){ многострочный комментарий }//однострочный комментарий
\стандартный однострочный комментарий( Комментарий до закрывающей скобки. Может быть многострочным (зависит от реализации). Пробел после открывающей скобки обязателен.)
c однострочный комментарий (в старых версиях Фортрана после латинской c должно идти 5 пробелов)! однострочный комментарий
<!-- многострочный комментарий -->
- Конфигурационные (ini) файлы
;неиспользуемый ключ либо другой комментарий
- Файлы реестра Windows (REG)
;неиспользуемый ключ либо другой комментарий
(* многострочный комментарий *)
# однострочный комментарий
(* многострочный комментарий *){ многострочный комментарий }
#однострочный комментарий=pod
аналог многострочного комментария, используется для написания документации=cut
#однострочный комментарий<#многострочный комментарий#>
#однострочный комментарий
--однострочный комментарий/* многострочный комментарий */
=begin- многострочный комментарий
=end#однострочный комментарий
"многострочный комментарий"
%однострочный комментарий
'однострочный комментарийRemоднострочный комментарий
-- однострочный комментарий--[[многострочныйкомментарий]]--[[многострочныйкомментарий]]--
Комментарии должны игнорироваться транслятором, но на практике это не всегда так. Некоторые специальные команды транслятору, сильно зависящие от реализации языка программирования, часто оформляются как комментарии.
Например, в диалекте Турбо Паскаль псевдокомментарии {$I-} и {$I+} используются для отключения и включения стандартного контроля ошибок ввода-вывода. Похожие специальные комментарии используются в языке разметки HTML для указания типа SGML-документа, «экранирования» таблиц стилей и сценариев на языках JavaScript и VBScript:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
…
<STYLE TYPE="text/css">
<!--
… описание стилей
-->
</STYLE>
…
<SCRIPT TYPE="text/javascript">
<!-- скрыть содержимое сценария от старых браузеров
… код сценария на JavaScript
// конец скрытого содержимого -->
</SCRIPT>
Некоторые комментарии программисты используют в ходе своей работы. Подобные комментарии особенно полезны, когда над одним кодом работает несколько разработчиков. Так, комментарием TODO обычно помечают участок кода, который программист оставляет незавершённым, чтобы вернуться к нему позже. Комментарий FIXME помечает обнаруженную ошибку, которую решают исправить позже. Комментарий XXX обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.
Урок №9. Комментарии | Уроки С++
Обновл. 23 Июл 2019 |
Комментарий — это строка (или несколько строк) текста, которая вставляется в исходный код для объяснения того, что делает этот код. В C++ есть два типа комментариев: однострочные и многострочные.
Однострочные комментарии
Однострочные комментарии — это комментарии, которые пишутся после символов //. Они размещаются в отдельных строках и всё, что находится после этих символов комментирования, игнорируется компилятором. Например:
std::cout << «Hello, world!» << std::endl; // всё, что находится от начала двойного слеша — игнорируется компилятором
std::cout << «Hello, world!» << std::endl; // всё, что находится от начала двойного слеша — игнорируется компилятором |
Как правило, однострочные комментарии используются для объяснения одной строчки кода:
std::cout << «Hello, world!» << std::endl; // cout и endl находятся в библиотеке iostream std::cout << «It is so exciting!» << std::endl; // эти комментарии усложняют чтение кода std::cout << «Yeah!» << std::endl; // особенно, когда строки разной длины
std::cout << «Hello, world!» << std::endl; // cout и endl находятся в библиотеке iostream std::cout << «It is so exciting!» << std::endl; // эти комментарии усложняют чтение кода std::cout << «Yeah!» << std::endl; // особенно, когда строки разной длины |
Размещая комментарии справа от кода, мы затрудняем себе как чтение кода, так и чтение комментариев. Следовательно, однострочные комментарии лучше размещать над строками кода:
// cout и endl находятся в библиотеке iostream std::cout << «Hello, world!» << std::endl; // теперь уже легче читать std::cout << «It is so exciting!» << std::endl; // не так ли? std::cout << «Yeah!» << std::endl;
// cout и endl находятся в библиотеке iostream std::cout << «Hello, world!» << std::endl;
// теперь уже легче читать std::cout << «It is so exciting!» << std::endl;
// не так ли? std::cout << «Yeah!» << std::endl; |
Многострочные комментарии
Многострочные комментарии — это комментарии, которые пишутся между символами /* */. Всё, что находится между звёздочками, игнорируется компилятором:
/* Это многострочный комментарий. Эта строка игнорируется и эта тоже. */
/* Это многострочный комментарий. Эта строка игнорируется и эта тоже. */ |
Так как всё, что находится между звёздочками, игнорируется, то иногда вы можете наблюдать следующее:
/* Это многострочный комментарий. * Звёздочки слева * упрощают чтение текста */
/* Это многострочный комментарий. * Звёздочки слева * упрощают чтение текста */ |
Многострочные комментарии не могут быть вложенными (т.е. одни комментарии внутри других):
/* Это многострочный /* комментарий */ а это уже не комментарий */ // Верхний комментарий заканчивается перед первым */, а не перед вторым */
/* Это многострочный /* комментарий */ а это уже не комментарий */ // Верхний комментарий заканчивается перед первым */, а не перед вторым */ |
Правило: Никогда не используйте вложенные комментарии.
Как правильно писать комментарии?
Во-первых, на уровне библиотек/программ/функций комментарии отвечают на вопрос «ЧТО?»: «Что делают эти библиотеки/программы/функции?». Например:
// Эта программа вычисляет оценку студента за семестр на основе его оценок за модули // Эта функция использует метод Ньютона для вычисления корня функции // Следующий код генерирует случайное число
// Эта программа вычисляет оценку студента за семестр на основе его оценок за модули
// Эта функция использует метод Ньютона для вычисления корня функции // Следующий код генерирует случайное число |
Все эти комментарии позволяют понять, что делает программа, без необходимости смотреть на исходный код. Это особенно важно специалистам, работающим в команде, где не каждый специалист будет знаком со всем имеющимся кодом.
Во-вторых, внутри библиотек/программ/функций комментарии отвечают на вопрос «КАК?»: «Как код выполняет задание?»:
/* Для расчёта итоговой оценки студента, мы добавляем все его оценки за уроки и домашние задания, а затем делим получившееся число на общее количество оценок. Таким образом мы получаем средний балл студента. */
/* Для расчёта итоговой оценки студента, мы добавляем все его оценки за уроки и домашние задания, а затем делим получившееся число на общее количество оценок. Таким образом мы получаем средний балл студента. */ |
// Чтобы получить рандомный (случайный) элемент, мы выполняем следующее: // 1) Составляем список всех элементов. // 2) Вычисляем среднее значение для каждого элемента, исходя из его веса, цвета и цены. // 3) Выбираем любое число. // 4) Определяем соответствие элемента случайно выбранному числу. // 5) Возвращаем случайный элемент.
// Чтобы получить рандомный (случайный) элемент, мы выполняем следующее:
// 1) Составляем список всех элементов. // 2) Вычисляем среднее значение для каждого элемента, исходя из его веса, цвета и цены. // 3) Выбираем любое число. // 4) Определяем соответствие элемента случайно выбранному числу. // 5) Возвращаем случайный элемент. |
Эти комментарии позволяют пользователю понять, каким образом код выполняет поставленное ему задание.
В-третьих, на уровне стейтментов (однострочного кода) комментарии отвечают на вопрос «ПОЧЕМУ?»: «Почему код выполняет задание именно таким образом, а не другим?». Плохой комментарий на уровне стейтментов объясняет, что делает код. Если вы когда-нибудь писали код, который был настолько сложным, что нужен был комментарий, который бы объяснял, что он делает, то вам нужно было бы не писать комментарий, а переписывать целый код.
Примеры плохих и хороших однострочных комментариев:
Плохой комментарий:
// Присваиваем переменной sight значение 0 sight = 0;
// Присваиваем переменной sight значение 0 sight = 0; |
(По коду это и так понятно)
Хороший комментарий:
// Игрок выпил зелье слепоты и ничего не видит sight = 0;
// Игрок выпил зелье слепоты и ничего не видит sight = 0; |
(Теперь мы знаем, ПОЧЕМУ зрение у игрока равно нулю)
Плохой комментарий:
// Рассчитываем стоимость элементов cost = items / 2 * storePrice;
// Рассчитываем стоимость элементов cost = items / 2 * storePrice; |
(Да, мы видим, что здесь подсчёт стоимости, но почему элементы делятся на 2?)
Хороший комментарий:
// Нам нужно разделить все элементы на 2, потому что они куплены по парам cost = items / 2 * storePrice;
// Нам нужно разделить все элементы на 2, потому что они куплены по парам cost = items / 2 * storePrice; |
(Теперь понятно!)
Программистам часто приходится принимать трудные решения по поводу того, каким способом решить проблему. А комментарии и существуют для того, чтобы напомнить себе (или объяснить другим) причину, почему вы написали код именно так, а не иначе.
Хорошие комментарии:
// Мы решили использовать список вместо массива, потому что // массивы осуществляют медленную вставку.
// Мы решили использовать список вместо массива, потому что // массивы осуществляют медленную вставку. |
// Мы используем метод Ньютона для вычисления корня функции, так как // другого детерминистического способа решения этой задачи нет
// Мы используем метод Ньютона для вычисления корня функции, так как // другого детерминистического способа решения этой задачи нет |
И, наконец, комментарии нужно писать так, чтобы человек, который не имеет ни малейшего представления о том, что делает ваш код — смог в нём разобраться. Очень часто случаются ситуации, когда программист говорит: «Это же совершенно очевидно, что делает код! Я это точно не забуду». Угадайте, что случится через несколько недель или даже дней? Это не совершенно очевидно, и вы удивитесь, как скоро вы забудете, что делает ваш код. Вы (или кто-то другой) будете очень благодарны себе за то, что оставите комментарии, объясняя на человеческом языке что, как и почему делает ваш код. Читать отдельные строки кода — легко, понимать их логику и смысл — сложно.
Подытожим:
На уровне библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «ЧТО?».
Внутри библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «КАК?».
На уровне стейтментов оставляйте комментарии, отвечая на вопрос «ПОЧЕМУ?».
Закомментирование
Закомментировать код — это конвертировать одну или нескольких строк кода в комментарии. Таким образом, вы сможете (временно) исключить части кода от компиляции.
Чтобы закомментировать одну строчку кода, используйте однострочные символы комментирования //.
Не закомментировано:
Закомментировано:
// std::cout << 1;
// std::cout << 1; |
Чтобы закомментировать блок кода, используйте однострочные символы комментирования // на каждой строке или символы многострочного комментария /* */.
Не закомментировано:
std::cout << 1; std::cout << 2; std::cout << 3;
std::cout << 1; std::cout << 2; std::cout << 3; |
Закомментировано символами однострочного комментария:
// std::cout << 1; // std::cout << 2; // std::cout << 3;
// std::cout << 1; // std::cout << 2; // std::cout << 3; |
Закомментировано символами многострочного комментария:
/* std::cout << 1; std::cout << 2; std::cout << 3; */
/* std::cout << 1; std::cout << 2; std::cout << 3; */ |
Есть несколько причин, зачем использовать закомментирование:
Причина №1: Вы работаете над новой частью кода, которая пока что не рабочая, но вам нужно запустить программу. Компилятор не позволит выполнить программу, если в ней будут ошибки. Временное отделение нерабочего кода от рабочего комментированием позволит вам запустить программу. Когда код будет рабочий, то вы сможете его легко раскомментировать и продолжить работу.
Причина №2: Вы написали код, который компилируется, но работает не так как нужно и сейчас у вас нет времени с этим разбираться. Закомментируйте код, а затем, когда будет время, исправьте в нём ошибки.
Причина №3: Поиск корня ошибки. Если программа производит не те результаты (или вообще происходит сбой), полезно будет поочерёдно «отключать» части вашего кода, чтобы понять какие из них рабочие, а какие создают проблемы. Если вы закомментируете одну или несколько строчек кода и программа начнёт корректно работать (или пропадут сбои), шансы того, что последнее, что вы закомментировали, является ошибкой – очень велики. После этого вы сможете разобраться с тем, почему же этот код не работает так, как нужно.
Причина №4: Тестирование нового кода. Вместо удаления старого кода, вы можете его закомментировать и оставить для справки, пока не будете уверены, что ваш новый код работает так, как нужно. Как только вы будете уверены в новом коде, то сможете без проблем удалить старые фрагменты кода. Если же новый код у вас будет работать не так, как нужно, то вы сможете его удалить и выполнить откат к старому коду.
Примечание: Во всех следующих уроках я буду использовать комментарии в иллюстративных целях. Внимательные читатели смогут заметить, что по стандартам выше большинство из этих комментариев будут плохими. Но помните, что использовать я их буду в образовательных целях, а не для демонстрации хороших примеров.
Оценить статью:
Загрузка…За репост +20 к карме и моя благодарность!
ravesli.com
C++ — Комментарии в коде
Уважаемый пользователь! Реклама помогает поддерживать и развивать наш проект, делая его простым и удобным специально для Вас. Если проект интересный и важный для Вас, то отключите на нем блокировщик рекламы. Спасибо, что читаете сайт!
Комментарии программы — это пояснительные утверждения, которые вы можете включить в код C ++. Эти комментарии помогают всем, кто читает исходный код. Все языки программирования допускают некоторые формы комментариев.
C ++ поддерживает однострочные и многострочные комментарии. Все символы, доступные внутри любого комментария, игнорируются компилятором C ++.
С ++ комментарии начинаются с / * и заканчиваются на * /. Например:
/* This is a comment */
/* C++ comments can also
* span multiple lines
*/Комментарий также может начинаться с //, доходящего до конца строки. Например:
#include <iostream>
using namespace std;
main() {
cout << "Hello World"; // prints Hello World
return 0;
}Когда этот код скомпилирован, он будет игнорировать // prints Hello World, а окончательный исполняемый файл будет выдавать следующий результат:
Hello WorldВнутри / * и * / комментарий // символы не имеют особого значения. В комментарии //, / * и * / не имеют особого значения. Таким образом, вы можете «вложить» один вид комментария в другой вид. Например:
/* Comment out printing of Hello World:
cout << "Hello World"; // prints Hello World
*/
Уважаемый пользователь! Реклама помогает поддерживать и развивать наш проект, делая его простым и удобным специально для Вас. Если проект интересный и важный для Вас, то отключите на нем блокировщик рекламы. Спасибо, что читаете сайт!
unetway.com
КОММЕНТАРИЙ — это… Что такое КОММЕНТАРИЙ?
КОММЕНТАРИЙ — (от лат. commentarius заметки, толкование; иногда К. назывался «схолиями», греч. scholia) жанр филос. литературы, наиболее интенсивно разрабатываемый в эпохи господства авторитарного знания, основанного на истинах, данных в «откровении» и… … Философская энциклопедия
комментарий — См. объяснение не требует комментариев… Словарь русских синонимов и сходных по смыслу выражений. под. ред. Н. Абрамова, М.: Русские словари, 1999. комментарий объяснение, примечание; рассуждение, разъяснение, прочтение, интерпретация, освещение … Словарь синонимов
КОММЕНТАРИЙ — (от латинского commentarius заметки, толкование), 1) книжный комментарий (примечания) пояснения к тексту, часть научно справочного аппарата книги. 2) В системе средств массовой информации разновидность оперативного аналитического материала об… … Современная энциклопедия
КОММЕНТАРИЙ — (от лат. commentarius заметки толкование),1) книжный комментарий (примечания) пояснения к тексту, часть научно справочного аппарата книги.2) В системе средств массовой информации разновидность оперативного аналитического материала, разъясняющего… … Большой Энциклопедический словарь
Комментарий — см. Текстология. Литературная энциклопедия. В 11 т.; М.: издательство Коммунистической академии, Советская энциклопедия, Художественная литература. Под редакцией В. М. Фриче, А. В. Луначарского. 1929 1939 … Литературная энциклопедия
Комментарий — в языках программирования инструкция транслятору или интерпретатору об игнорировании отмеченного текста программы. Обычно комментарии используются для пояснительных текстов. См. также: Операторы в языках программирования Финансовый словарь Финам … Финансовый словарь
Комментарий — (от лат. commentarius заметки, толкование) 1) разновидность оперативного аналитического материала, разъясняющего смысл актуального общественно политические события, документа и т. п.; 2) книжный комментарий (примечания) пояснения к тексту, часть… … Политология. Словарь.
КОММЕНТАРИЙ — (от лат. commentarius – заметки, толкование). Толкование смысла какого л. слова, грамматического или стилистического явления, объяснение связей между лексическими единицами, особенностей отражения национальной культуры в слове и др. На занятиях… … Новый словарь методических терминов и понятий (теория и практика обучения языкам)
комментарий — комментарий, род. мн. комментариев (неправильно комментарий) … Словарь трудностей произношения и ударения в современном русском языке
Комментарий — (от латинского commentarius заметки, толкование), 1) книжный комментарий (примечания) пояснения к тексту, часть научно справочного аппарата книги. 2) В системе средств массовой информации разновидность оперативного аналитического материала об… … Иллюстрированный энциклопедический словарь
Комментарий — разъяснения, пояснения к тексту документа, закона, нормативного акта Словарь бизнес терминов. Академик.ру. 2001 … Словарь бизнес-терминов
dic.academic.ru
комментарий — Викисловарь
Морфологические и синтаксические свойства
| падеж | ед. ч. | мн. ч. |
|---|---|---|
| Им. | коммента́рий | коммента́рии |
| Р. | коммента́рия | коммента́риев |
| Д. | коммента́рию | коммента́риям |
| В. | коммента́рий | коммента́рии |
| Тв. | коммента́рием | коммента́риями |
| Пр. | коммента́рии | коммента́риях |
ком-мен-та́-рий
Существительное, неодушевлённое, мужской род, 2-е склонение (тип склонения 7a по классификации А. А. Зализняка).
Корень: -коммент-; суффикс: -арий [Тихонов, 1996].
Произношение
- МФА: [kəmʲɪnˈtarʲɪɪ̯]
Семантические свойства
Значение
- пояснения, разъяснительные примечания к какому-либо тексту, его толкование ◆ Комментарии к роману А. С. Пушкина «Евгений Онегин». Мы не могли обойти вниманием такое важное событие и наши юристы подготовили квалифицированные комментарии ко всем семи разделам первой части кодекса.
- рассуждения, пояснительные или критические замечания по поводу чего-либо ◆ Добавлять комментарии на нашем сайте могут только зарегистрированные пользователи, поэтому для начала авторизуйтесь или зарегистрируйтесь. Без комментариев. Комментарии излишни.
Синонимы
- пояснения, примечания, толкование
- рассуждения
Антонимы
- —
- —
Гиперонимы
- —
- замечания
Гипонимы
- —
- критика
Родственные слова
Этимология
Происходит от лат. commentarius «заметки, записки; комментарий, толкование», от гл. commentari «обдумывать», далее из comminisci «вспоминать; выдумывать», далее из cum (варианты co-, com-, con-) «с, вместе» + memini «помнить», из праиндоевр. *men- «думать, помнить».
Фразеологизмы и устойчивые сочетания
Перевод
ru.wiktionary.org
Комментарии (программирование) — это… Что такое Комментарии (программирование)?
У этого термина существуют и другие значения, см. Комментарий.Коммента́рии — пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии — часть текста программы, не влияющая на её семантику. Комментарии не оказывают никакого влияния на результат компиляции программы или её интерпретацию. Помимо исходных текстов программ, комментарии также применяются в языках разметки и языках описания.
Назначение комментариев
Большинство специалистов сходятся во мнении, что комментарии должны объяснять намерения программиста, а не код; то, что можно выразить на языке программирования, не должно выноситься в комментарии — в частности, надо использовать говорящие названия переменных, функций, классов, методов и пр., разбивать программу на лёгкие для понимания части, стремиться к тому, чтобы структура классов и структура баз данных были максимально понятными и прозрачными и т. д. Есть даже мнение (его придерживаются в экстремальном программировании и некоторых других гибких методологиях программирования), что если для понимания программы требуются комментарии — значит, она плохо написана.
Концепция грамотного программирования настаивает на включение в текст программы настолько подробных и продуманных комментариев, чтобы она стала исходным текстом не только для исполняемого кода, но и для сопроводительной документации.
Комментарии часто используются для временного отключения части кода. В языках C и C++, некоторые рекомендуют использовать с той же целью директивы препроцессора (#if 0 … #endif).
Однострочные и многострочные комментарии
С точки зрения синтаксиса, существуют два вида комментариев. Многострочный комментарий может иметь любую длину, он отмечается специальными символами в начале и конце (например, /* */). Некоторые языки позволяют вложение многострочных комментариев, другие — нет.
Однострочный комментарий отмечается специальным символом в начале (например, //) и продолжается до конца строки. Обычно допускается вложение однострочных комментариев в другие, как одно- так и многострочные комментарии. Способы записи можно чередовать, с точки зрения семантики они одинаковы.
Аннотации
Другой вид комментариев — аннотации — применяется в набросках доказательств правильности программ. Такие комментарии описывают состояние компьютера, когда программа в процессе выполнения достигнет точки, где расположен комментарий. Программа, снабжённая комментариями-аннотациями, называется аннотированной программой.
Автоматическая генерация документации
Специальным образом оформленные комментарии (т. н. документирующие комментарии) используются для автоматического создания документации, в первую очередь, к библиотекам функций или классов. Для этого используются генераторы документации, например, такие как javadoc[1] для языка Java, phpDocumentor для PHP[2], doxygen[3] для C и C++ и др.
Документирующие комментарии как правило оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.
Пример документирующего комментария
/** * Имя или краткое описание объекта * * Развернутое описание * * @имя_дескриптора значение * @return тип_данных */
В некоторых средах программирования (например, Eclipse, NetBeans, Python, Visual Studio) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций.
Трансляция программ
Во время трансляции комментарии распознаются на стадии лексического анализа (и, соответственно, считаются лексемами). Распознавание на стадии препроцессирования накладно и даже чревато ошибками; включение комментариев в синтаксические диаграммы практически невозможно.
В различных языках и средах программирования
;однострочный комментарийCOMMENT +…Многострочный комментарий.+Строка с этим символом завершает комментарий, вместо плюса может быть другой символ.
\стандартный однострочный комментарий( Комментарий до закрывающей скобки. Может быть многострочным (зависит от реализации). Пробел после открывающей скобки обязателен.)
'однострочный комментарий> — поддерживается не во всех диалектахREMоднострочный комментарий
;однострочный комментарий
- BAT-файлы и команды DOS
REMоднострочный комментарий::однострочный комментарий
#однострочный комментарий
/*многострочный комментарий*///однострочный комментарий#однострочный комментарий (для PHP)- Способ комментирования больших кусков кода в C/C++. Используется не для написания комментариев к программе, а для временного сокрытия части функциональности (в Java и JavaScript невозможен):
#if 0…кусок кода…#endif
* (на седьмой позиции)— однострочный комментарий
(* многострочный комментарий *){ многострочный комментарий }//однострочный комментарий
c однострочный комментарий (в старых версиях Фортрана после латинской c должно идти 5 пробелов)! однострочный комментарий
<!-- многострочный комментарий -->
- Конфигурационные (ini) файлы
;неиспользуемый ключ либо другой комментарий
- Файлы реестра Windows (REG)
;неиспользуемый ключ либо другой комментарий
- Система аналитических вычислений Mathematica
(* многострочный комментарий *)
- Система аналитических вычислений Maple
# однострочный комментарий
(* многострочный комментарий *){ многострочный комментарий }
#однострочный комментарий=pod
аналог многострочного комментария, используется для написания документации=cut
#однострочный комментарий
--однострочный комментарий/* многострочный комментарий */
=begin- многострочный комментарий
=end#однострочный комментарий
"многострочный комментарий"
%однострочный комментарий
'однострочный комментарийRemоднострочный комментарий
-- однострочный комментарий--[[многострочныйкомментарий]]--[[многострочныйкомментарий]]--
Специальные комментарии
Комментарии должны игнорироваться транслятором, но на практике это не всегда так. Некоторые специальные команды транслятору, сильно зависящие от реализации языка программирования, часто оформляются как комментарии.
Например в диалекте Турбо Паскаль псевдокомментарии {$I-} и {$I+} используются для отключения и включения стандартного контроля ошибок ввода-вывода. Похожие специальные комментарии используются в языке разметки HTML для указания типа SGML-документа, «экранирования» таблиц стилей и сценариев на языках JavaScript и VBScript:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
…
<STYLE TYPE="text/css">
<!--
… описание стилей
-->
</STYLE>
…
<SCRIPT TYPE="text/javascript">
<!-- скрыть содержимое сценария от старых браузеров
… код сценария на JavaScript
// конец скрытого содержимого -->
</SCRIPT>
Некоторые комментарии программисты используют в ходе своей работы. Подобные комментарии особенно полезны, когда над одним кодом работает несколько разработчиков. Так, комментарием TODO обычно помечают участок кода, который программист оставляет незавершённым, чтобы вернуться к нему позже. Комментарий FIXME помечает обнаруженную ошибку, которую решают исправить позже. Комментарий XXX обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.
Примечания
См. также
dic.academic.ru
комментарий — это… Что такое комментарий?
КОММЕНТАРИЙ — (от лат. commentarius заметки, толкование; иногда К. назывался «схолиями», греч. scholia) жанр филос. литературы, наиболее интенсивно разрабатываемый в эпохи господства авторитарного знания, основанного на истинах, данных в «откровении» и… … Философская энциклопедия
комментарий — См. объяснение не требует комментариев… Словарь русских синонимов и сходных по смыслу выражений. под. ред. Н. Абрамова, М.: Русские словари, 1999. комментарий объяснение, примечание; рассуждение, разъяснение, прочтение, интерпретация, освещение … Словарь синонимов
КОММЕНТАРИЙ — (от латинского commentarius заметки, толкование), 1) книжный комментарий (примечания) пояснения к тексту, часть научно справочного аппарата книги. 2) В системе средств массовой информации разновидность оперативного аналитического материала об… … Современная энциклопедия
КОММЕНТАРИЙ — (от лат. commentarius заметки толкование),1) книжный комментарий (примечания) пояснения к тексту, часть научно справочного аппарата книги.2) В системе средств массовой информации разновидность оперативного аналитического материала, разъясняющего… … Большой Энциклопедический словарь
Комментарий — см. Текстология. Литературная энциклопедия. В 11 т.; М.: издательство Коммунистической академии, Советская энциклопедия, Художественная литература. Под редакцией В. М. Фриче, А. В. Луначарского. 1929 1939 … Литературная энциклопедия
Комментарий — в языках программирования инструкция транслятору или интерпретатору об игнорировании отмеченного текста программы. Обычно комментарии используются для пояснительных текстов. См. также: Операторы в языках программирования Финансовый словарь Финам … Финансовый словарь
Комментарий — (от лат. commentarius заметки, толкование) 1) разновидность оперативного аналитического материала, разъясняющего смысл актуального общественно политические события, документа и т. п.; 2) книжный комментарий (примечания) пояснения к тексту, часть… … Политология. Словарь.
КОММЕНТАРИЙ — (от лат. commentarius – заметки, толкование). Толкование смысла какого л. слова, грамматического или стилистического явления, объяснение связей между лексическими единицами, особенностей отражения национальной культуры в слове и др. На занятиях… … Новый словарь методических терминов и понятий (теория и практика обучения языкам)
комментарий — комментарий, род. мн. комментариев (неправильно комментарий) … Словарь трудностей произношения и ударения в современном русском языке
Комментарий — (от латинского commentarius заметки, толкование), 1) книжный комментарий (примечания) пояснения к тексту, часть научно справочного аппарата книги. 2) В системе средств массовой информации разновидность оперативного аналитического материала об… … Иллюстрированный энциклопедический словарь
Комментарий — разъяснения, пояснения к тексту документа, закона, нормативного акта Словарь бизнес терминов. Академик.ру. 2001 … Словарь бизнес-терминов
popular.academic.ru