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

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

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

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

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

Комментарии часто используются для временного отключения части кода. В языках C и C++ , некоторые ^{[

кто?

]} рекомендуют использовать с той же целью директивы препроцессора ( #if 0 … #endif ).

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

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

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

Аннотации

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

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

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

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

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

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

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

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

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

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

1С

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

--

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

Ассемблер

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


       COMMENT +

…

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

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

Бейсик

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

REM

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

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

источник не указан 1391 день

]}