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

Материал из Википедии — свободной энциклопедии

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

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

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

[править] Аннотации

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

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

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

[править] Трансляция программ

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