|
Комментарии (программирование)Коммента́рии — пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии — часть текста программы, не влияющая на её семантику. Комментарии не оказывают никакого влияния на результат компиляции программы или её интерпретацию. Помимо исходных текстов программ, комментарии также применяются в языках разметки и языках описания. Назначение комментариевБольшинство специалистов сходятся во мнении, что комментарии должны объяснять намерения программиста, а не код; то, что можно выразить на языке программирования, не должно выноситься в комментарии — в частности, надо использовать говорящие названия переменных, функций, классов, методов и других сущностей (см. Соглашения об именах), разбивать программу на лёгкие для понимания части, стремиться к тому, чтобы структура классов и структура баз данных были максимально понятными и прозрачными и т. д. Есть даже мнение (его придерживаются в экстремальном программировании и некоторых других гибких методологиях программирования), что если для понимания программы требуются комментарии — значит, она плохо написана. Концепция грамотного программирования настаивает на включение в текст программы настолько подробных и продуманных комментариев, чтобы она стала исходным текстом не только для исполняемого кода, но и для сопроводительной документации. Комментарии часто используются для временного отключения части кода.
В языках C и C++, некоторые[кто?] рекомендуют использовать с той же целью директивы препроцессора ( Однострочные и многострочные комментарииС точки зрения синтаксиса, существуют два вида комментариев. Многострочный комментарий может иметь любую длину, он отмечается специальными символами в начале и конце (например, Однострочный комментарий отмечается специальным символом в начале (например, АннотацииДругой вид комментариев — аннотации — применяется в набросках доказательств правильности программ. Такие комментарии описывают состояние компьютера, когда программа в процессе выполнения достигнет точки, где расположен комментарий. Программа, снабжённая комментариями-аннотациями, называется аннотированной программой. Автоматическая генерация документацииСпециальным образом оформленные комментарии (т. н. документирующие комментарии) используются для автоматического создания документации, в первую очередь, к библиотекам функций или классов. Для этого используются генераторы документации, например, такие как javadoc[1] для языка Java, phpDocumentor для PHP[2], doxygen[3] для C и C++ и др. Документирующие комментарии как правило оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками. Пример документирующего комментария /**
* Имя или краткое описание объекта
*
* Развёрнутое описание
*
* @имя_дескриптора значение
* @return тип_данных
*/
В некоторых средах программирования (например, Eclipse, NetBeans, Python, Visual Studio) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций. Трансляция программВо время трансляции комментарии распознаются на стадии лексического анализа (и, соответственно, считаются лексемами). Распознавание на стадии препроцессирования накладно и даже чревато ошибками; включение комментариев в синтаксические диаграммы практически невозможно. В различных языках и средах программирования
Специальные комментарииКомментарии должны игнорироваться транслятором, но на практике это не всегда так. Некоторые специальные команды транслятору, сильно зависящие от реализации языка программирования, часто оформляются как комментарии. Например, в диалекте Турбо Паскаль псевдокомментарии <!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 обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.[источник не указан 1698 дней] См. такжеПримечания
|