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

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

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

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

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

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

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

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

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

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

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

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

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

• 1С

  // однострочный комментарий

• Ада

-- однострочный комментарий

• Ассемблер

; однострочный комментарий

COMMENT +

… Многострочный комментарий.

+ Строка с этим символом завершает комментарий, вместо плюса может быть другой символ.

• Бейсик

' однострочный комментарий> — поддерживается не во всех диалектах

REM однострочный комментарий

• BLITZ PLUS

; однострочный комментарий

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

REM однострочный комментарий

:: однострочный комментарий

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

# однострочный комментарий

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

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

// однострочный комментарий

# однострочный комментарий (для PHP)

Способ комментирования больших кусков кода в C/C++. Используется не для написания комментариев к программе, а для временного сокрытия части функциональности (в Java и JavaScript невозможен):

#if 0

…кусок кода…

#endif

• Кобол

* (на седьмой позиции)  — однострочный комментарий

• Delphi (Object Pascal)

(* многострочный комментарий *)

{ многострочный комментарий }

// однострочный комментарий

• Форт

\ стандартный однострочный комментарий

( Комментарий до закрывающей скобки. Может быть многострочным (зависит от реализации). Пробел после открывающей скобки обязателен.)

• Фортран

c однострочный комментарий (в старых версиях Фортрана после латинской c должно идти 5 пробелов)

! однострочный комментарий

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

<!-- многострочный комментарий -->

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

; неиспользуемый ключ либо другой комментарий

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

; неиспользуемый ключ либо другой комментарий

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

(* многострочный комментарий *)

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

# однострочный комментарий

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

(* многострочный комментарий *)

{ многострочный комментарий }

• Perl

# однострочный комментарий

=pod
аналог многострочного комментария, используется для написания документации

=cut

• PowerShell

# однострочный комментарий

<# многострочный комментарий #>

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

# однострочный комментарий

• PL/SQL

-- однострочный комментарий

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

• Ruby

=begin

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

=end

# однострочный комментарий

• Smalltalk

"многострочный комментарий"

• TeX, LaTeX, PostScript

% однострочный комментарий

• Visual Basic

' однострочный комментарий

Rem однострочный комментарий

• Lua

-- однострочный комментарий

--[[многострочный

комментарий]]

--[[многострочный

комментарий]]--

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

Например, в диалекте Турбо Паскаль псевдокомментарии {$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 обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.

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