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


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

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

Содержание

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

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

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

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

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

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

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

Аннотации

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

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

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

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

Пример документирующего комментария

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

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

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

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

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

; однострочный комментарий
COMMENT +
Многострочный комментарий.
+ Строка с этим символом завершает комментарий, вместо плюса может быть другой символ.
\ стандартный однострочный комментарий
( Комментарий до закрывающей скобки. Может быть многострочным (зависит от реализации). Пробел после открывающей скобки обязателен.)
' однострочный комментарий> — поддерживается не во всех диалектах
REM однострочный комментарий
  • BLITZ PLUS
; однострочный комментарий
  • 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 обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.

Примечания

См. также


Wikimedia Foundation. 2010.

Смотреть что такое "Комментарии (программирование)" в других словарях:

  • Комментарии — (программирование) Комментарии (газета) Cписок значений слова или словосочетания со ссылками на соответствующие статьи …   Википедия

  • Комментарий (программирование) — Комментарии  пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии  часть текста… …   Википедия

  • Литературное программирование — или (английский термин намеренно двусмыслен) Грамотное программирование (англ. Literate Programming) концепция, методология программирования и документирования. Термин и саму концепцию разработал Дональд Кнут в 1981 году при разработке системы… …   Википедия

  • Современное проектирование на С++: Обобщенное программирование и прикладные шаблоны проектирования — Modern C++ Design Автор: Андрей Александреску Жанр: кни …   Википедия

  • Отчет об ошибке (программирование) — Содержание 1 Введение 2 Создание отчета об ошибке 2.1 Mac OS X 2.2 Windows …   Википедия

  • Директива (программирование) — У этого термина существуют и другие значения, см. Директива (значения). В программировании термин «директива» (указание) по использованию похож на термин «команда», так как также используется для описания некоторых конструкций языка… …   Википедия

  • Листинг (программирование) — Исходный код, написанный на JavaScript Исходный код (также исходный текст)  текст компьютерной программы на каком либо языке программирования. В обобщённом смысле  любые входные данные для транслятора. Исходный код либо транслируется в… …   Википедия

  • Отчёт об ошибке (программирование) — Содержание 1 Введение 2 Создание отчета об ошибке 2.1 Mac OS X 2.2 Windows …   Википедия

  • Комментарий — Комментарии (программирование) Комментарий (пост, сообщение) Комментарий (файл) …   Википедия

  • C++ — У этого термина существуют и другие значения, см. C. См. также: Си (язык программирования) C++ Семантика: мультипарадигмальный: объектно ориентированное, обобщённое, процедурное, метапрограммирование Тип исполнения: компилируемый Появился в …   Википедия

Книги

Другие книги по запросу «Комментарии (программирование)» >>