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

Поделись знанием:
Перейти к: навигация, поиск
У этого термина существуют и другие значения, см. Комментарий.

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





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

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

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

Комментарии часто используются для временного отключения части кода. В языках 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" "www.w3.org/TR/REC-html40/strict.dtd">
…
<STYLE TYPE="text/css">
<!--
… описание стилей
-->
</STYLE>
…
<SCRIPT TYPE="text/javascript">
 <!-- скрыть содержимое сценария от старых браузеров
 … код сценария на JavaScript
 // конец скрытого содержимого -->
</SCRIPT>

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

Напишите отзыв о статье "Комментарии (программирование)"

Примечания

  1. ↑ [java.sun.com/j2se/javadoc/ java.sun.com/j2se/javadoc]
  2. ↑ [www.phpdoc.org phpdoc.org]
  3. ↑ [www.doxygen.org doxygen.org]

См. также

Отрывок, характеризующий Комментарии (программирование)

– Вот я же вам говорил, – сказал Алпатыч, вступая в свои права. – Нехорошо, ребята!
– Глупость наша, Яков Алпатыч, – отвечали голоса, и толпа тотчас же стала расходиться и рассыпаться по деревне.
Связанных двух мужиков повели на барский двор. Два пьяные мужика шли за ними.
– Эх, посмотрю я на тебя! – говорил один из них, обращаясь к Карпу.
– Разве можно так с господами говорить? Ты думал что?
– Дурак, – подтверждал другой, – право, дурак!
Через два часа подводы стояли на дворе богучаровского дома. Мужики оживленно выносили и укладывали на подводы господские вещи, и Дрон, по желанию княжны Марьи выпущенный из рундука, куда его заперли, стоя на дворе, распоряжался мужиками.
– Ты ее так дурно не клади, – говорил один из мужиков, высокий человек с круглым улыбающимся лицом, принимая из рук горничной шкатулку. – Она ведь тоже денег стоит. Что же ты ее так то вот бросишь или пол веревку – а она потрется. Я так не люблю. А чтоб все честно, по закону было. Вот так то под рогожку, да сенцом прикрой, вот и важно. Любо!
– Ишь книг то, книг, – сказал другой мужик, выносивший библиотечные шкафы князя Андрея. – Ты не цепляй! А грузно, ребята, книги здоровые!
– Да, писали, не гуляли! – значительно подмигнув, сказал высокий круглолицый мужик, указывая на толстые лексиконы, лежавшие сверху.

Ростов, не желая навязывать свое знакомство княжне, не пошел к ней, а остался в деревне, ожидая ее выезда. Дождавшись выезда экипажей княжны Марьи из дома, Ростов сел верхом и до пути, занятого нашими войсками, в двенадцати верстах от Богучарова, верхом провожал ее. В Янкове, на постоялом дворе, он простился с нею почтительно, в первый раз позволив себе поцеловать ее руку.
– Как вам не совестно, – краснея, отвечал он княжне Марье на выражение благодарности за ее спасенье (как она называла его поступок), – каждый становой сделал бы то же. Если бы нам только приходилось воевать с мужиками, мы бы не допустили так далеко неприятеля, – говорил он, стыдясь чего то и стараясь переменить разговор. – Я счастлив только, что имел случай познакомиться с вами. Прощайте, княжна, желаю вам счастия и утешения и желаю встретиться с вами при более счастливых условиях. Ежели вы не хотите заставить краснеть меня, пожалуйста, не благодарите.
Но княжна, если не благодарила более словами, благодарила его всем выражением своего сиявшего благодарностью и нежностью лица. Она не могла верить ему, что ей не за что благодарить его. Напротив, для нее несомненно было то, что ежели бы его не было, то она, наверное, должна была бы погибнуть и от бунтовщиков и от французов; что он, для того чтобы спасти ее, подвергал себя самым очевидным и страшным опасностям; и еще несомненнее было то, что он был человек с высокой и благородной душой, который умел понять ее положение и горе. Его добрые и честные глаза с выступившими на них слезами, в то время как она сама, заплакав, говорила с ним о своей потере, не выходили из ее воображения.
Когда она простилась с ним и осталась одна, княжна Марья вдруг почувствовала в глазах слезы, и тут уж не в первый раз ей представился странный вопрос, любит ли она его?
По дороге дальше к Москве, несмотря на то, что положение княжны было не радостно, Дуняша, ехавшая с ней в карете, не раз замечала, что княжна, высунувшись в окно кареты, чему то радостно и грустно улыбалась.
«Ну что же, ежели бы я и полюбила его? – думала княжна Марья.
Как ни стыдно ей было признаться себе, что она первая полюбила человека, который, может быть, никогда не полюбит ее, она утешала себя мыслью, что никто никогда не узнает этого и что она не будет виновата, ежели будет до конца жизни, никому не говоря о том, любить того, которого она любила в первый и в последний раз.
Иногда она вспоминала его взгляды, его участие, его слова, и ей казалось счастье не невозможным. И тогда то Дуняша замечала, что она, улыбаясь, глядела в окно кареты.
«И надо было ему приехать в Богучарово, и в эту самую минуту! – думала княжна Марья. – И надо было его сестре отказать князю Андрею! – И во всем этом княжна Марья видела волю провиденья.
Впечатление, произведенное на Ростова княжной Марьей, было очень приятное. Когда ои вспоминал про нее, ему становилось весело, и когда товарищи, узнав о бывшем с ним приключении в Богучарове, шутили ему, что он, поехав за сеном, подцепил одну из самых богатых невест в России, Ростов сердился. Он сердился именно потому, что мысль о женитьбе на приятной для него, кроткой княжне Марье с огромным состоянием не раз против его воли приходила ему в голову. Для себя лично Николай не мог желать жены лучше княжны Марьи: женитьба на ней сделала бы счастье графини – его матери, и поправила бы дела его отца; и даже – Николай чувствовал это – сделала бы счастье княжны Марьи. Но Соня? И данное слово? И от этого то Ростов сердился, когда ему шутили о княжне Болконской.


Приняв командование над армиями, Кутузов вспомнил о князе Андрее и послал ему приказание прибыть в главную квартиру.
Князь Андрей приехал в Царево Займище в тот самый день и в то самое время дня, когда Кутузов делал первый смотр войскам. Князь Андрей остановился в деревне у дома священника, у которого стоял экипаж главнокомандующего, и сел на лавочке у ворот, ожидая светлейшего, как все называли теперь Кутузова. На поле за деревней слышны были то звуки полковой музыки, то рев огромного количества голосов, кричавших «ура!новому главнокомандующему. Тут же у ворот, шагах в десяти от князя Андрея, пользуясь отсутствием князя и прекрасной погодой, стояли два денщика, курьер и дворецкий. Черноватый, обросший усами и бакенбардами, маленький гусарский подполковник подъехал к воротам и, взглянув на князя Андрея, спросил: здесь ли стоит светлейший и скоро ли он будет?
Князь Андрей сказал, что он не принадлежит к штабу светлейшего и тоже приезжий. Гусарский подполковник обратился к нарядному денщику, и денщик главнокомандующего сказал ему с той особенной презрительностью, с которой говорят денщики главнокомандующих с офицерами:
– Что, светлейший? Должно быть, сейчас будет. Вам что?
Гусарский подполковник усмехнулся в усы на тон денщика, слез с лошади, отдал ее вестовому и подошел к Болконскому, слегка поклонившись ему. Болконский посторонился на лавке. Гусарский подполковник сел подле него.
– Тоже дожидаетесь главнокомандующего? – заговорил гусарский подполковник. – Говог'ят, всем доступен, слава богу. А то с колбасниками беда! Недаг'ом Ег'молов в немцы пг'осился. Тепег'ь авось и г'усским говог'ить можно будет. А то чег'т знает что делали. Все отступали, все отступали. Вы делали поход? – спросил он.
– Имел удовольствие, – отвечал князь Андрей, – не только участвовать в отступлении, но и потерять в этом отступлении все, что имел дорогого, не говоря об именьях и родном доме… отца, который умер с горя. Я смоленский.
– А?.. Вы князь Болконский? Очень г'ад познакомиться: подполковник Денисов, более известный под именем Васьки, – сказал Денисов, пожимая руку князя Андрея и с особенно добрым вниманием вглядываясь в лицо Болконского. – Да, я слышал, – сказал он с сочувствием и, помолчав немного, продолжал: – Вот и скифская война. Это все хог'ошо, только не для тех, кто своими боками отдувается. А вы – князь Андг'ей Болконский? – Он покачал головой. – Очень г'ад, князь, очень г'ад познакомиться, – прибавил он опять с грустной улыбкой, пожимая ему руку.
Князь Андрей знал Денисова по рассказам Наташи о ее первом женихе. Это воспоминанье и сладко и больно перенесло его теперь к тем болезненным ощущениям, о которых он последнее время давно уже не думал, но которые все таки были в его душе. В последнее время столько других и таких серьезных впечатлений, как оставление Смоленска, его приезд в Лысые Горы, недавнее известно о смерти отца, – столько ощущений было испытано им, что эти воспоминания уже давно не приходили ему и, когда пришли, далеко не подействовали на него с прежней силой. И для Денисова тот ряд воспоминаний, которые вызвало имя Болконского, было далекое, поэтическое прошедшее, когда он, после ужина и пения Наташи, сам не зная как, сделал предложение пятнадцатилетней девочке. Он улыбнулся воспоминаниям того времени и своей любви к Наташе и тотчас же перешел к тому, что страстно и исключительно теперь занимало его. Это был план кампании, который он придумал, служа во время отступления на аванпостах. Он представлял этот план Барклаю де Толли и теперь намерен был представить его Кутузову. План основывался на том, что операционная линия французов слишком растянута и что вместо того, или вместе с тем, чтобы действовать с фронта, загораживая дорогу французам, нужно было действовать на их сообщения. Он начал разъяснять свой план князю Андрею.
– Они не могут удержать всей этой линии. Это невозможно, я отвечаю, что пг'ог'ву их; дайте мне пятьсот человек, я г'азог'ву их, это вег'но! Одна система – паг'тизанская.


Источник — «http://wiki-org.ru/wiki/index.php?title=Комментарии_(программирование)&oldid=75013065»