Из Википедии, бесплатной энциклопедии
Перейти к навигации Перейти к поиску
Комментарии в разметке Википедии см . В разделах Help: Wiki markup # Character formatting и WP: COMMENT .
Иллюстрация исходного кода Java с комментариями пролога, выделенными красным, и встроенными комментариями зеленым . Программный код выделен синим цветом .

В компьютерном программировании , комментарий программист-читаемое объяснение или аннотации в исходном коде в виде компьютерной программы . Они добавляются с целью облегчения понимания исходного кода людьми и обычно игнорируются компиляторами и интерпретаторами . [1] [2] синтаксис комментариев на различных языках программирования значительно варьируется.

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

Гибкость, обеспечиваемая комментариями, допускает широкую степень вариативности, но формальные соглашения об их использовании обычно являются частью руководств по стилю программирования.

Обзор [ править ]

Комментарии , как правило , в формате либо блок комментарии (также называемые пролога комментариев или комментарии потока ) или комментарии линии (также называемые встроенные комментарии ). [3]

Блочные комментарии ограничивают область исходного кода, которая может занимать несколько строк или часть одной строки. Эта область указывается с помощью начального и конечного разделителей. Некоторые языки программирования (такие как MATLAB ) позволяют рекурсивно вкладывать блочные комментарии друг в друга, но другие (например, Java ) этого не делают. [4] [5] [6]

Комментарии к строке либо начинаются с разделителя комментариев и продолжаются до конца строки, либо, в некоторых случаях, начинаются с определенного столбца (смещения строки символов) в исходном коде и продолжаются до конца строки. [6]

Некоторые языки программирования используют как блочные, так и строчные комментарии с разными разделителями комментариев. Например, C ++ , имеет блок комментарии , ограниченные /*и */которые могут занимать несколько строк и комментарии строки , ограниченные //. Другие языки поддерживают только один тип комментариев. Например, комментарии Ada - это строковые комментарии: они начинаются --и продолжаются до конца строки. [6]

Использует [ редактировать ]

Вопрос о том, как лучше использовать комментарии, является предметом спора; разные комментаторы высказывали различные, а иногда и противоположные точки зрения. [7] [8] Есть много разных способов написания комментариев, и многие комментаторы предлагают противоречивые советы. [8]

Планирование и проверка [ править ]

Комментарии могут использоваться как форма псевдокода для обозначения намерения до написания фактического кода. В этом случае он должен объяснять логику кода, а не сам код. .

/ * цикл назад по всем элементам, возвращаемым сервером (они должны обрабатываться в хронологическом порядке) * / for  ( i  =  ( numElementsReturned  -  1 );  i  > =  0 ;  i - )  {  / * обрабатывать данные каждого элемента * /  updatePattern ( я ,  returnElements [ я ]); }

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

Описание кода [ править ]

Комментарии могут использоваться для обобщения кода или для объяснения намерений программиста. Согласно этой точке зрения, повторение кода на простом английском языке считается излишним; необходимость повторного объяснения кода может быть признаком того, что он слишком сложен и его следует переписать, или что название плохое.

«Не документируйте плохой код - перепишите его». [9]
«Хорошие комментарии не повторяют код и не объясняют его. Они разъясняют его цель. Комментарии должны объяснять на более высоком уровне абстракции, чем код, то, что вы пытаетесь сделать». [10]

Комментарии также могут использоваться для объяснения того, почему блок кода не соответствует соглашениям или передовым практикам. Это особенно верно для проектов, требующих очень мало времени на разработку или исправления ошибок. Например:

'Вторая переменная неактивна из-за ошибок сервера, возникающих при повторном использовании данных формы. Нет документации по проблеме поведения сервера, поэтому просто пишите код. vtx  =  сервер . mappath ( "локальные настройки" )

Алгоритмическое описание [ править ]

Иногда исходный код содержит новое или заслуживающее внимания решение конкретной проблемы. В таких случаях комментарии могут содержать объяснение методологии. Такие объяснения могут включать диаграммы и формальные математические доказательства. Это может представлять собой объяснение кода, а не разъяснение его цели; но другие, которым поручено поддерживать кодовую базу, могут найти такое объяснение решающим. Это может быть особенно верно в случае узкоспециализированных проблемных областей; или редко используемые оптимизации, конструкции или вызовы функций. [11]

Например, программист может добавить комментарий, чтобы объяснить, почему была выбрана сортировка вставкой вместо быстрой , поскольку первая теоретически медленнее, чем вторая. Это можно было бы записать так:

 list  =  [ f  ( b ),  f  ( b ),  f  ( c ),  f  ( d ),  f  ( a ),  ... ] ;  // Нужна стабильная сортировка. К тому же производительность действительно не имеет значения.  insert_sort  ( список );

Включение ресурсов [ править ]

Логотипы , диаграммы и блок-схемы, состоящие из художественных конструкций ASCII, могут быть вставлены в исходный код в формате комментария. [12] Кроме того, уведомления об авторских правах могут быть встроены в исходный код в виде комментариев. Двоичные данные также могут быть закодированы в комментариях с помощью процесса, известного как двоичное кодирование в текст , хотя такая практика встречается редко и обычно относится к файлам внешних ресурсов.

Следующий фрагмент кода представляет собой простую диаграмму ASCII, изображающую поток процесса для сценария системного администрирования, содержащегося в файле сценария Windows, работающем под Windows Script Host . Хотя раздел, обозначающий код, отображается как комментарий, сама диаграмма фактически появляется в разделе XML CDATA , который технически считается отдельным от комментариев, но может служить аналогичным целям. [13]

<! - begin: wsf_resource_nodes -> <resource  id = "ProcessDiagram000" > <! [CDATA [ HostApp (Main_process)  |  V script.wsf (app_cmd) -> ClientApp (async_run, batch_process)  |  |  В  mru.ini (mru_history) ]]> </resource>

Хотя эту идентичную диаграмму можно было бы легко включить в качестве комментария, пример иллюстрирует один случай, когда программист может отказаться от использования комментариев как способа включения ресурсов в исходный код. [13]

Метаданные [ править ]

Основная статья: Метаданные

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

В частности, многие специалисты по сопровождению программного обеспечения помещают инструкции по отправке в комментарии, чтобы помочь людям, читающим исходный код этой программы, отправить любые улучшения, которые они вносят, обратно разработчику.

Другие метаданные включают: имя создателя исходной версии программного файла и дату создания первой версии, имя текущего сопровождающего программы, имена других людей, которые редактировали файл программы до сих пор. , URL-адрес документации о том, как использовать программу, название лицензии на программное обеспечение для этого программного файла и т. д.

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

Отладка [ править ]

Обычная практика является разработчиком , чтобы закомментировать на фрагмент кода , то есть , чтобы добавить комментарий синтаксиса вызывает этот блок кода , чтобы стать комментарием, так что она не будет выполнена в окончательной программе. Это может быть сделано для исключения определенных фрагментов кода из окончательной программы или (что чаще) может быть использовано для поиска источника ошибки. Систематически комментируя и запуская части программы, можно определить источник ошибки и исправить ее.

Ниже приведен пример комментирования кода в целях исключения:

 if  ( opt . equals  ( "e" ))  opt_enabled  =  true ; / * if (opt.equals ("d"))  opt_debug = true; * / если  ( opt . equals  ( "v" ))  opt_verbose  =  true ;

Приведенный выше фрагмент кода предполагает, что программист по какой-то причине решил отключить опцию отладки.

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

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

Основная статья: Генератор документации

Инструменты программирования иногда хранят документацию и метаданные в комментариях. [14] Они могут включать в себя вставке позиций для автоматического включения заголовочного файла, команду для установки файла подсветки синтаксиса режима, [15] или файл номер версии . [16] Эти комментарии функционального управления также обычно называют аннотациями . Хранение документации в комментариях к исходному коду считается одним из способов упростить процесс документирования, а также повысить шансы на то, что документация будет обновляться с изменениями в коде. [17]

Примеры генераторов документации включают программы Javadoc для использования с Java , Ddoc для D , Doxygen для C , C ++ , Java, IDL , Visual Expert для PL / SQL , Transact-SQL , PowerBuilder и PHPDoc для PHP . Формы строки документации поддерживаются Python , Lisp , Elixir и Clojure . [18]

В C # , F # и Visual Basic .NET реализована аналогичная функция, называемая «XML-комментарии», которые IntelliSense считывает из скомпилированной сборки .NET . [19]

Расширение синтаксиса [ править ]

Иногда элементы синтаксиса, которые изначально предназначались для комментариев, повторно используются для передачи дополнительной информации программе, такой как « условные комментарии ». Такие «горячие комментарии» могут быть единственным практическим решением, которое поддерживает обратную совместимость, но многие считают их кладжем . [20]

Директива использует [ править ]

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

Двумя примерами такого руководства переводчиком являются:

  • Unix " shebang " - #!используется в первой строке скрипта для указания на используемый интерпретатор.
  • «Волшебные комментарии», идентифицирующие кодировку, которую использует исходный файл, [21] например, Python PEP 263. [22]

В приведенном ниже сценарии для Unix-подобной системы показаны оба этих варианта использования:

#! / usr / bin / env python3 # - * - кодировка: UTF-8 - * -
print ( «Тестирование» )

В некоторой степени похоже на использование комментариев в C, чтобы сообщить компилятору, что "провал" по умолчанию в операторе case был сделан намеренно:

переключатель  ( команда )  {  case  CMD_SHOW_HELP_AND_EXIT :  do_show_help ();  / *  Прохождение * / case  CMD_EXIT :  do_exit ();  перерыв ;  case  CMD_OTHER :  do_other ();  перерыв ;  / * ... и т. д ... * /  }

Добавление такого /* Fall thru */комментария для читателей-людей уже было обычным явлением, но в 2017 году компилятор gcc начал искать эти (или другие признаки преднамеренного намерения) и, если они не были найдены, выдавал: «предупреждение: это утверждение может провалиться» . [23]

Многие редакторы и IDE будут читать комментарии в специальном формате. Например, функция «Modeline» в Vim ; который изменил бы обработку вкладок при редактировании источника с этим комментарием, включенным в верхней части файла:

# vim: tabstop = 8 expandtab shiftwidth = 4 softtabstop = 4

Снятие стресса [ править ]

Иногда программисты добавляют комментарии, чтобы снять стресс, рассказывая об инструментах разработки, конкурентах, работодателях, условиях работы или качестве самого кода. [24] Возникновение этого явления легко увидеть из онлайн-ресурсов, отслеживающих ненормативную лексику в исходном коде. [25]

Нормативные представления [ править ]

Существуют различные нормативные точки зрения и давние мнения относительно правильного использования комментариев в исходном коде. [26] [27] Некоторые из них являются неформальными и основаны на личных предпочтениях, в то время как другие публикуются или обнародуются в качестве официальных руководящих принципов для конкретного сообщества. [28]

Нужны комментарии [ править ]

У экспертов разные точки зрения на то, уместны ли комментарии в исходном коде и когда. [9] [29] Некоторые утверждают, что исходный код должен быть написан с небольшим количеством комментариев, исходя из того, что исходный код должен быть самоочевидным или самодокументированным . [9] Другие предполагают, что код следует подробно комментировать (нередко более 50% непробельных символов в исходном коде содержатся в комментариях). [30] [31]

Между этими представлениями находится утверждение, что комментарии не являются ни полезными, ни вредными сами по себе, и важно то, что они верны и синхронизируются с исходным кодом и опускаются, если они излишни, чрезмерны, трудны в обслуживании или по другим причинам бесполезны. [32] [33]

Комментарии иногда используются для документирования контрактов при проектировании посредством контрактного подхода к программированию.

Уровень детализации [ править ]

В зависимости от целевой аудитории кода и других соображений уровень детализации и описания может значительно различаться.

Например, следующий комментарий Java подойдет во вводном тексте, предназначенном для обучения начинающему программированию:

 Строка  s  =  "Википедия" ;  / * Присваивает значение "Википедия" переменной s. * /

Однако такой уровень детализации не подходит для производственного кода или других ситуаций, в которых участвуют опытные разработчики. Такие элементарные описания несовместимы с правилом: «Хорошие комментарии ... проясняют намерения». [10] Кроме того, для профессиональных сред кодирования уровень детализации обычно хорошо определяется для удовлетворения конкретных требований к производительности, определяемых бизнес-операциями. [31]

Стили [ править ]

При рассмотрении того, как комментарии должны отображаться в исходном коде, доступно множество стилистических альтернатив. Для более крупных проектов, в которых участвует группа разработчиков, стили комментариев либо согласовываются до начала проекта, либо развиваются по условию или необходимости по мере роста проекта. Обычно программисты отдают предпочтение стилям, которые согласованы, не мешают работе, легко модифицируются и трудно сломать. [34]

Заблокировать комментарий [ редактировать ]

Следующие фрагменты кода на языке C демонстрируют лишь крошечный пример того, как комментарии могут различаться стилистически, при этом передавая ту же основную информацию:

/ *  Это тело комментария.  Вариант первый. * /
/ ************************** \ * * * Это тело комментария. * * Второй вариант. * * * \ *************************** /

Такие факторы, как личные предпочтения, гибкость инструментов программирования и другие соображения, как правило, влияют на стилистические варианты, используемые в исходном коде. Например, второй вариант может не понравиться программистам, у которых нет редакторов исходного кода, которые могут автоматизировать выравнивание и внешний вид текста в комментариях.

Консультант по программному обеспечению и технический обозреватель Аллен Голуб [35] - один из экспертов, который выступает за выравнивание левых краев комментариев: [36]

 / * Это стиль, рекомендованный Holub для C и C ++.  * Это продемонстрировано в «Достаточно веревки» в правиле 29.  * /
 / * Это еще один способ сделать это, также в C. ** Это проще сделать в редакторах, которые не делают автоматически отступ от второй ** до последней строки комментария на один пробел от первой. ** Это также используется в книге Голуба, в правиле 31. * /

Использование / * и * / в качестве разделителей комментариев к блокам было унаследовано от PL / I в языке программирования B, непосредственном предшественнике языка программирования C. [37]

Комментарии к строке [ править ]

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

В этом примере игнорируется весь текст от символов ASCII // до конца строки.

// ------------------------- // Это тело комментария. // -------------------------

Часто такой комментарий должен начинаться с крайнего левого угла и распространяться на всю строку. Тем не менее, во многих языках, можно также поместить комментарий инлайн с помощью командной строки, чтобы добавить комментарий к ней - как в этом примере Perl:

напечатать  $ s  .  "\ п" ;  # Добавить символ новой строки после печати

Если язык допускает и строковые комментарии, и блочные комментарии, группы программирования могут принять решение об их использовании по-разному: например, строчные комментарии только для второстепенных комментариев и блочные комментарии для описания абстракций более высокого уровня.

Теги [ редактировать ]

Программисты могут использовать неформальные теги в комментариях, чтобы помочь в индексировании распространенных проблем. Затем их можно будет искать с помощью обычных инструментов программирования, таких как утилита Unix grep, или даже с выделением синтаксиса в текстовых редакторах . Их иногда называют «кодовыми метками» [38] [39] или «токенами». [40]

Такие теги сильно различаются, но могут включать:

  • BUG - известная ошибка, которую необходимо исправить.
  • FIXME - надо поправить.
  • HACK - обходной путь.
  • TODO - что-то нужно сделать.
  • UNDONE - разворот или «откат» предыдущего кода.
  • XXX - предупреждать других программистов о проблемном или вводящем в заблуждение коде

Примеры [ править ]

Сравнение [ править ]

Основная статья: Сравнение языков программирования (синтаксис) § Комментарии

Типографские условные обозначения комментариев сильно различаются. Кроме того, отдельные языки программирования иногда предоставляют уникальные варианты. Для подробного обзора, пожалуйста, обратитесь к статье сравнения языков программирования .

Ада [ править ]

В языке программирования Ada знак «-» используется для обозначения комментария до конца строки.

Например:

 - задача авиадиспетчера принимает запросы на взлет и посадку  задача  типа  контроллера  ( My_Runway : Runway_Access )  это  - записей задач для синхронной передачи сообщений  ввода  Request_Takeoff  ( ID : в  Airplane_ID ;  Взлет : из  Runway_Access );  запись  Request_Approach ( ID : в  Airplane_ID ;  подход : вне  Runway_Access );  end  Controller ;

APL [ править ]

APL используется ⍝для обозначения комментария до конца строки.

Например:

⍝ Теперь сложите числа: c ← a + b  ⍝ сложение

В диалектах с примитивами ⊣("left") и ⊢("right") комментарии часто могут быть внутри или отдельными операторами в форме игнорируемых строк:

d ← 2 × c  ⊣ 'где' ⊢  c ← a +  'bound' ⊢  b

AppleScript [ править ]

В этом разделе кода AppleScript показаны два стиля комментариев, используемых в этом языке.

(* Эта программа отображает приветствие. *) На  Greet ( myGreeting )  диалогового дисплея  myGreeting  и  "мир!" конец  приветствовать- Показать приветственное приветствие ( «Привет» )

BASIC [ править ]

В этом классическом фрагменте кода раннего BASIC ключевое слово REM ( «Замечание» ) используется для добавления комментариев.

10 REM Эта ОСНОВНАЯ программа показывает использование операторов PRINT и GOTO. 15 REM Заполняет экран фразой «HELLO» 20 PRINT «HELLO» 30 GOTO 20

В более поздних версиях Microsoft BASIC, включая Quick Basic , Q Basic , Visual Basic , Visual Basic .NET и VB Script ; а в потомках, таких как FreeBASIC и Gambas, любой текст в строке после символа '(апостроф) также рассматривается как комментарий.

Пример в Visual Basic .NET:

Открытый  класс  Form1  Private  Sub  Button1_Click ( отправитель  как  объект ,  e  как  EventArgs )  обрабатывает  Button1 . Нажмите  «Следующий код выполняется, когда пользователь  » нажимает кнопку в окне программы.  rem комментарии все еще существуют. MessageBox . Show ( "Hello, World" )  'Показать всплывающее окно с приветствием  End  Sub End  Class

C [ править ]

Этот фрагмент кода C демонстрирует использование комментария пролога или «блочного комментария» для описания цели условного оператора . Комментарий объясняет ключевые термины и концепции и включает короткую подпись программиста, создавшего код.

 / *  * Проверяем, не превысили ли мы максимальное количество процессов, но обязательно  * исключите root. Это необходимо для того, чтобы логин и  * друзья могли установить ограничение  на количество процессов для каждого пользователя ниже *, чем количество запущенных процессов root. - Rik  * /  if  ( atomic_read ( & p -> пользователь -> процессы )  > =  p -> rlim [ RLIMIT_NPROC ]. Rlim_cur  &&  ! Способный ( CAP_SYS_ADMIN )  &&  ! Способный ( CAP_SYS_RESOURCE )) goto  bad_fork_free ;

Начиная с C99, также стало возможным использовать синтаксис // из C ++, указывающий на однострочный комментарий.

Конфигурация Cisco IOS и IOS-XE [ править ]

Восклицательный ( ! ) Могут быть использованы для комментариев метки в режиме конфигурации маршрутизатора Cisco, однако такие комментарии не сохраняются в энергонезависимой памяти (который содержит загрузочную-конфигурации), и они не отображаются командой «шоу запустить» . [41] [42]

Можно вставить удобочитаемый контент, который на самом деле является частью конфигурации и может быть сохранен в загрузочной конфигурации NVRAM с помощью:

  • Команда "description", используемая для добавления описания к конфигурации интерфейса или соседа BGP.
  • Параметр "name", чтобы добавить примечание к статическому маршруту.
  • Команда "замечание" в списках доступа
! Вставьте текст ниже, чтобы перенаправить трафик вручнуюconfig tint gi0 / 2не закрывайip route 0.0.0.0 0.0.0.0 gi0 / 2 имя ISP2нет IP-маршрута 0.0.0.0 0.0.0.0 gi0 / 1 имя ISP1int gi0 / 1закрытьвыход

ColdFusion [ править ]

ColdFusion использует комментарии, аналогичные комментариям HTML , но вместо двух тире использует три. Эти комментарии перехватываются механизмом ColdFusion и не выводятся в браузер.

 <! --- Это напечатает "Hello World" в браузере. --->  <cfoutput> Hello World < бр  />  </ cfoutput>

Фортран IV [ править ]

Этот фрагмент кода Fortran IV демонстрирует, как комментарии используются на этом языке, который очень ориентирован на столбцы. Буква «C» в столбце 1 означает, что вся строка рассматривается как комментарий.

C C Строки, начинающиеся с буквы «C» (в первом столбце или столбце «комментарий»), представляют собой комментарии C WRITE ( 6 , 610 )  610 FORMAT ( 12 H HELLO WORLD ) END

Обратите внимание, что в противном случае столбцы строки обрабатываются как четыре поля: от 1 до 5 - это поле метки, 6 заставляет строку считаться продолжением предыдущего оператора; а декларации и заявления идут с 7 по 72.

Fortran 90 [ править ]

Этот фрагмент кода Fortran демонстрирует, как комментарии используются на этом языке, причем сами комментарии описывают основные правила форматирования.

! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! * Все символы после восклицательного знака считаются комментариями * ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * программа comment_test  print  '(A)' ,  'Hello world'  ! В Fortran 90 появилась возможность встроенных комментариев. конец программы

Haskell [ править ]

Комментарии к строке в Haskell начинаются с символа «-» (два дефиса) до конца строки, а комментарии к нескольким строкам начинаются с символа «{-» и заканчиваются знаком «-}».

{- это комментарий к другим строкам -} - и это комментарий к одной строке putStrLn  "Wikipedia"  - это еще один комментарий

Haskell также предлагает грамотный метод комментирования, известный как «Bird Style». [43] Здесь все строки, начинающиеся с>, интерпретируются как код, все остальное считается комментарием. Еще одно дополнительное требование - всегда оставлять пустую строку до и после блока кода:

В стиле птицы перед кодом нужно оставить пробел.> fact  ::  Integer  ->  Integer > fact  0  =  1 > fact  ( n + 1 )  =  ( n + 1 )  *  fact  nИ вы также должны оставить пустую строку после кода.

Грамотное программирование также можно выполнить на Haskell, используя LaTeX . Среда кода может использоваться вместо стиля Ричарда Берда: в стиле LaTeX это эквивалентно приведенному выше примеру, среда кода может быть определена в преамбуле LaTeX. Вот простое определение:

\ usepackage { verbatim } \ newenvironment { code } { \ verbatim } { \ endverbatim }

позже

% Источнику LaTeX файлу \ глагол | факт п | вызов функции вычисляет $ n ! $ if $ n \ ge 0 $ , вот определение: \\ \ begin { code } fact :: Integer -> Целочисленный факт 0 = 1 факт ( n + 1 ) = ( n + 1 ) * fact n \ end { code }
Здесь больше объяснений с использованием              Разметка \ LaTeX {}

Java [ править ]

Этот фрагмент кода Java показывает комментарий блока, используемый для описания setToolTipTextметода. Форматирование соответствует стандартам Javadoc Sun Microsystems . Комментарий предназначен для чтения процессором Javadoc.

/ ** * Это блочный комментарий в Java. * Метод setToolTipText регистрирует текст для отображения во всплывающей подсказке. * Текст отображается, когда курсор задерживается над компонентом. * * @param text Строка для отображения. Если 'text' имеет значение NULL, * подсказка для этого компонента отключена. * / public  void  setToolTipText ( String  text )  {  // Это встроенный комментарий в Java. ЗАДАЧА: Напишите код для этого метода. }

JavaScript [ править ]

JavaScript использует // перед комментариями и / * * / для многострочных комментариев.

// Однострочный комментарий JavaScript var  iNum  =  100 ; var  iTwo  =  2 ;  // Комментарий в конце строки / * многострочный комментарий JavaScript * /

Lua [ править ]

В языке программирования Lua-- для однострочных комментариев используются двойные дефисы, аналогично языкам Ada , Eiffel , Haskell , SQL и VHDL . Lua также имеет блочные комментарии, которые начинаются --[[и продолжаются до закрытия.]]

Например:

- [[Многострочный длинный комментарий ]] print ( 20 )  - распечатать результат

Распространенный метод комментирования фрагмента кода [44] - заключить код между --[[и --]], как показано ниже:

- [[ print (10) -]] - никаких действий (закомментировано)

В этом случае можно повторно активировать код, добавив один дефис в первую строку:

--- [[ print ( 10 ) -]] -> 10

В первом примере символ --[[в первой строке начинает длинный комментарий, а два дефиса в последней строке все еще находятся внутри этого комментария. Во втором примере последовательность ---[[начинается с обычного однострочного комментария, так что первая и последняя строки становятся независимыми комментариями. В данном случае printэто посторонние комментарии. В этом случае последняя строка становится независимым комментарием, так как начинается с --.

Длинные комментарии в Lua могут быть более сложными, чем эти, как вы можете прочитать в разделе «Длинные строки» в разделе « Программирование на Lua» .

MATLAB [ править ]

В языке программирования MATLAB символ '%' указывает однострочный комментарий. Многострочные комментарии также доступны через скобки% {и%} и могут быть вложенными, например

% Это производные для каждого члена d  =  [ 0  - 1  0 ];% {  % {  (Пример вложенного комментария, отступы для косметики (и игнорируются).)  %}  Мы  образуем  в  последовательность,  следуя  за  Тейлор  формулы.  Обратите внимание ,  что  мы ' повторно  действующий  на  в  векторе . %} seq  =  d  . *  ( x  -  c ) . ^ n  ./ ( факториал ( n ))% Добавляем, чтобы получить приближение Тейлора около  =  сумма ( далее )

Ним [ править ]

Ним использует символ «#» для встроенных комментариев. Комментарии к многострочным блокам начинаются с '# [' и закрываются '] #'. Комментарии к многострочным блокам могут быть вложенными.

У Nim также есть комментарии к документации, в которых используются смешанные разметки Markdown и ReStructuredText . Комментарии встроенной документации используют '##', а комментарии многострочной блочной документации открываются с помощью '## [' и закрываются с помощью '] ##. Компилятор может генерировать документацию HTML , LaTeX и JSON из комментариев к документации. Комментарии к документации являются частью абстрактного синтаксического дерева и могут быть извлечены с помощью макросов. [45]

## Документация модуля * ReSTructuredText * и ** MarkDown ** # Это комментарий, но не комментарий документации.type  Kitten  =  object  ## Документация типа  age :  int  ## Документация поляproc purr ( self :  Kitten )  =  ## Документация по функции  echo  "Purr Purr"  # Это комментарий, но не комментарий документации.# Это комментарий, но не комментарий документации.

OCaml [ править ]

OCaml использует вложенные комментарии, что полезно при комментировании блока кода.

codeLine (* уровень комментария 1 (* уровень комментария 2 *) *)

Паскаль [ править ]

В семействе языков Паскаля Никлауса Вирта (включая Модула-2 и Оберон ) комментарии открываются с помощью '(*' и заканчиваются '*)'.

Например:

(* тестовые диагонали *) columnDifference  : =  testColumn  -  столбец ; если  ( row  +  columnDifference  =  testRow )  или  .......

В современных диалектах Паскаля вместо них используются '{' и '}'. [46]

Perl [ править ]

Строчные комментарии в Perl и многих других языках сценариев начинаются с символа решетки (#). 

# Простой пример # my  $ s  =  "Wikipedia" ;  # Устанавливает для переменной s значение "Википедия". напечатать  $ s  .  "\ п" ;  # Добавить символ новой строки после печати

Вместо обычной конструкции блочного комментирования Perl использует Plain Old Documentation , язык разметки для грамотного программирования , [47] например: [48]

= элемент Pod :: List-E <gt> new ()Создайте новый объект списка. Свойства могут быть указаны через хеш- ссылку следующим образом: мой $ list = Pod :: List-> new ({-start => $., -indent => 4});См. Подробности об отдельных методах / свойствах.= вырезатьsub  новый  {  мой  $ this  =  shift ;  мой  $ class  =  ref ( $ this )  ||  $ this ;  мой  % params  =  @_ ;  мой  $ self  =  { % params };  благослови  $ self ,  $ class ;  $ self -> initialize ();  return  $ self ; }

R [ править ]

R поддерживает только встроенные комментарии, начинающиеся с символа решетки (#).

# Это комментарий print ( "Это не комментарий" )  # Это еще один комментарий

Раку [ править ]

Raku (ранее называвшийся Perl 6) использует те же строковые комментарии и комментарии к документации POD, что и обычный Perl (см. Раздел Perl выше), но добавляет настраиваемый тип комментария блока: «многострочные / встроенные комментарии». [49]

Они начинаются с символа решетки, за которым следует обратная кавычка, затем некоторый открывающий символ скобки и заканчиваются соответствующим закрывающим символом скобки. [49] Контент может не только занимать несколько строк, но также может быть встроен в строку.

# `{{" комментирование "этой версии toggle-case (Str: D $ s)Переключает регистр каждого символа в строке: мой Str $ toggled-string = toggle-case («МОЕ ИМЯ - МИХАЭЛ!»);}}sub  toggle-case ( Str: D  $ s ) # `(сейчас используется эта версия скобок) { ...}

PHP [ править ]

Комментарии в PHP могут быть либо в стиле C ++ (как строчные, так и блочные), либо использовать хеши. PHPDoc - это стиль, адаптированный из Javadoc, который является общим стандартом для документирования кода PHP.

PowerShell [ править ]

Комментарии в Windows PowerShell

# Однострочный комментарий Write-Host  "Hello, World!"<# Мульти  линия  Комментарий #>Написать-Host  "Прощай, мир!"

Python [ править ]

Встроенные комментарии в Python используют символ решетки (#), как в двух примерах этого кода:

# Эта программа выводит на экран "Hello World" print ( "Hello World!" )  # Обратите внимание на новый синтаксис

Блочные комментарии, как определено в этой статье, технически не существуют в Python. [50] Можно использовать пустой строковый литерал, представленный строкой в тройных кавычках, [51] но не игнорируется интерпретатором так же, как комментарий "#". [50] В приведенных ниже примерах строки с тройными двойными кавычками действуют таким образом как комментарии, но также рассматриваются как строки документации :

"" " Предположим, что это файл mymodule.py, тогда эта строка, будучи первым оператором в файле, станет строкой документации модуля mymodule при импорте файла. " ""class  MyClass :  "" "Строка документации класса" "" def  my_method ( self ):  "" " Строка документации метода" ""def  my_function ():  "" "Строка документации функции" ""

Руби [ править ]

Комментарии в Ruby .

Однострочный комментарий: (строка начинается с решетки "#")

ставит  "Это не комментарий"# это комментарийставит  "Это не комментарий"

Многострочные комментарии: (комментарии помещаются между ключевыми словами "начало" и "конец")

ставит  "Это не комментарий"= начатьвсе, что идет в этих строкахтолько для человеческого читателя= конецставит  "Это не комментарий"

SQL [ править ]

Стандартные комментарии в SQL имеют однострочную форму с двумя дефисами:

- Это однострочный комментарий, за которым следует вторая строка SELECT  COUNT ( * )  FROM  Authors  WHERE  Authors . name  =  'Смит' ;  - Примечание: нам нужен только smith  - этот комментарий появляется после кода SQL

В качестве альтернативы синтаксис формата комментария, идентичный стилю «блочного комментария», используемому в синтаксисе для C и Java, поддерживается Transact-SQL , MySQL , SQLite , PostgreSQL и Oracle . [52] [53] [54] [55] [56]

MySQL также поддерживает комментарии от символа решетки (#) до конца строки.

Swift [ править ]

Однострочные комментарии начинаются с двух косых черт (//):

// Это комментарий.

Многострочные комментарии начинаются с косой черты, за которой следует звездочка (/ *), и заканчиваются звездочкой, за которой следует косая черта (* /):

/ * Это тоже комментарий, но он записан в несколько строк. * /

Многострочные комментарии в Swift могут быть вложены в другие многострочные комментарии. Вы пишете вложенные комментарии, начиная с многострочного блока комментариев, а затем начиная второй многострочный комментарий внутри первого блока. Затем закрывается второй блок, за ним следует первый блок:

/ * Это начало первого многострочного комментария. / * Это второй вложенный многострочный комментарий. * / Это конец первого многострочного комментария. * /

XML [ править ]

Комментарии в XML (или HTML) вводятся с помощью

<! -

и может растягиваться на несколько строк до терминатора, 

->

Например,

<! - выберите здесь контекст -> <param  name = "context"  value = "public"  />

Проблемы безопасности [ править ]

В интерпретируемых языках комментарии доступны для просмотра конечному пользователю программы. В некоторых случаях, например, если разделы кода «закомментированы», это может представлять уязвимость системы безопасности . [57]

См. Также [ править ]

  • Строка документации - особый тип комментария, который анализируется и сохраняется в течение всего времени выполнения программы.
  • Шебанг , использование #! как директива интерпретатора в скриптах на Unix-подобных системах
  • Тег комментария HTML
  • Грамотное программирование , альтернативная парадигма документации
  • Синтаксис комментариев на разных языках программирования

Примечания и ссылки [ править ]

  1. ^ Исходный код можно разделить на программный код (который состоит из машинно-переводимых инструкций); и комментарии (которые включают удобочитаемые заметки и другие виды аннотаций в поддержку программного кода). Пенни Грабб, Армстронг Таканг (2003). Сопровождение программного обеспечения: концепции и практика . World Scientific. С. 7, пожалуйста, начало120–121. ISBN 978-981-238-426-3.
  2. ^ Для целей этой статьи комментарии языка программирования рассматриваются как неотличимые от комментариев, которые появляются в языках разметки , файлах конфигурации и других подобных контекстах. Более того, язык разметки часто тесно интегрирован с кодом языка программирования, особенно в контексте генерации кода . См., Например, Ganguli, Madhushree (2002). Использование Jsp . Нью-Йорк: Вили. ISBN 978-0-471-21974-3., Хьюитт, Эбен (2003). Java для разработчиков Coldfusion . Верхняя река Сэдл: образование Пирсона. ISBN 978-0-13-046180-3.
  3. ^ Диксит, JB (2003). Основы работы с компьютером и программирования в C . Публикации Лакшми. ISBN 978-81-7008-882-0.
  4. ^ Хайэм, Десмонд (2005). Руководство по MATLAB . СИАМ. ISBN 978-0-89871-578-1.
  5. ^ Vermeulen, Al (2000). Элементы стиля Java . Издательство Кембриджского университета. ISBN 978-0-521-77768-1.
  6. ^ a b c «Использование правильного комментария в Java» . 2000-03-04 . Проверено 24 июля 2007 .
  7. ^ WR, Дитрих (2003). Прикладное распознавание образов: алгоритмы и реализация на C ++ . Springer. ISBN 978-3-528-35558-6.предлагает точки зрения на правильное использование комментариев в исходном коде. п. 66.
  8. ^ a b Киз, Джессика (2003). Справочник по программной инженерии . CRC Press. ISBN 978-0-8493-1479-7.обсуждает комментарии и «Наука о документации» стр. 256.
  9. ^ a b c Элементы стиля программирования , Керниган и Плаугер
  10. ^ a b Код завершен , МакКоннелл
  11. ^ Спинеллис, Diomidis (2003). Чтение кода: перспектива открытого исходного кода . Эддисон-Уэсли. ISBN 978-0-201-79940-8.
  12. ^ «CodePlotter 1.6 - Добавляйте и редактируйте диаграммы в коде с помощью этого инструмента, похожего на Visio» . Архивировано из оригинала на 2007-07-14 . Проверено 24 июля 2007 .
  13. ^ a b Niederst, Дженнифер (2006). Краткий обзор веб-дизайна: краткий справочник по настольному компьютеру . О'Рейли. ISBN 978-0-596-00987-8.Иногда разница между «комментарием» и другими элементами синтаксиса языка программирования или разметки влечет за собой тонкие нюансы. Нидерст указывает на одну из таких ситуаций, заявив: «К сожалению, программное обеспечение XML считает комментарии неважной информацией и может просто удалить комментарии из документа перед его обработкой. Чтобы избежать этой проблемы, используйте вместо этого раздел XML CDATA».
  14. ^ См., Например, Винн-Пауэлл, Род (2008). Mac Os X для фотографов: оптимизированный процесс обработки изображений для пользователей Mac . Оксфорд: Focal Press. ISBN 978-0-240-52027-8. стр. 243
  15. ^ Лэмб, Линда (1998). Изучение редактора VI . Севастополь: O'Reilly & Associates. ISBN 978-1-56592-426-0. описывает использование синтаксиса модельной строки в файлах конфигурации Vim.
  16. ^ См., Например, Берлин, Даниэль (2006). Практическая Subversion, второе издание . Беркли: АПресс. ISBN 978-1-59059-753-8. стр.168.
  17. ^ Эмблер, Скотт (2004). Учебник по объектам: гибкая разработка на основе моделей с использованием UML 2.0 . Издательство Кембриджского университета. ISBN 978-1-397-80521-8.
  18. ^ Определение функции со строкой документации в Clojure
  19. ^ Murach. C # 2005 . п. 56.
  20. ^ c2: Горячие комментарии
  21. ^ "Кодировка класса" . Руби . ruby-lang.org . Проверено 5 декабря 2018 .
  22. ^ «PEP 263 - Определение кодировок исходного кода Python» . Python.org . Проверено 5 декабря 2018 .
  23. ^ Poláček, Marek (2017-03-10). «-Wimplicit-fallthrough в GCC 7» . Разработчик Red Hat . Красная шляпа . Проверено 10 февраля 2019 .
  24. ^ «Программисты Microsoft скрывали кучу ненормативной лексики в раннем программном коде» , Лиза Эдичико, 27 марта 2014 г., businessinsider.com.au
  25. ^ (см., например, Linux Swear Count ).
  26. ^ Goodliffe, Пит (2006). Code Craft . Сан-Франциско: Пресса без крахмала. ISBN 978-1-59327-119-0.
  27. ^ Смит, Т. (1991). Принципы и методы промежуточного программирования с использованием Паскаля . Бельмонт: Западный паб. Co. ISBN 978-0-314-66314-6.
  28. ^ См., Например, Колецке, Питер (2000). Расширенные формы и отчеты Oracle Developer . Беркли: Осборн / Макгроу-Хилл. ISBN 978-0-07-212048-6. стр.65.
  29. ^ «Худшая практика - плохие комментарии» . Проверено 24 июля 2007 .
  30. ^ Морелли, Ральф (2006). Java, Java, Java: объектно-ориентированное решение проблем . Колледж Прентис Холл. ISBN 978-0-13-147434-5.
  31. ^ a b «Как писать комментарии к документам для инструмента Javadoc Tool» . Проверено 24 июля 2007 .Руководства Javadoc указывают, что комментарии имеют решающее значение для платформы. Кроме того, соответствующий уровень детализации довольно четко определен: «Мы тратим время и усилия, сосредоточенные на указании граничных условий, диапазонов аргументов и угловых случаев, а не на определении общих терминов программирования, написании концептуальных обзоров и включении примеров для разработчиков».
  32. ^ Юрдон, Эдвард (2007). Методики построения и дизайна программ . Университет Мичигана. 013901702X.Несуществующие комментарии могут затруднить понимание кода, но комментарии могут быть вредными, если они устарели, избыточны, неверны или иным образом затрудняют понимание предполагаемой цели исходного кода.
  33. Перейти ↑ Dewhurst, Stephen C (2002). C ++ Gotchas: Как избежать общих проблем в кодировании и дизайне . Эддисон-Уэсли Профессионал. ISBN 978-0-321-12518-7.
  34. ^ «Стиль кодирования» . Архивировано из оригинала на 2007-08-08 . Проверено 24 июля 2007 .
  35. ^ "Аллен Голуб" . Архивировано из оригинала на 2007-07-20 . Проверено 24 июля 2007 .
  36. ^ Аллен Голуб, Достаточно веревки, чтобы выстрелить себе в ногу , ISBN 0-07-029689-8 , 1995, McGraw-Hill 
  37. ^ Кен Томпсон. «Ссылка пользователей на B» . Проверено 21 июля 2017 .
  38. ^ "PEP 0350 - Codetags" , Python Software Foundation
  39. ^ «Никогда не забывайте ничего до, после и во время кодирования» , используя комментарии «codetag» в качестве продуктивных остатков
  40. ^ «Использование списка задач» , msdn.microsoft.com
  41. ^ "Оставить комментарий в running-config" . Cisco Learning Network (дискуссионный форум) .
  42. ^ «Руководство по настройке файлов конфигурации, Cisco IOS XE Release 3S (серия ASR 900)» .
  43. ^ «Грамотное программирование» . haskell.org .
  44. ^ «Программирование на Lua 1.3» . www.Lua.org . Проверено 8 ноября 2017 .
  45. ^ macros.extractDocCommentsAndRunnables
  46. ^ «Комментарии» . www.freepascal.org . Проверено 20 сентября 2017 .
  47. ^ "perlpod - простой формат старой документации" . Проверено 12 сентября 2011 .
  48. ^ "Pod :: ParseUtils - помощники для синтаксического анализа и преобразования POD" . Проверено 12 сентября 2011 .
  49. ^ a b «Документация по Perl 6 - Синтаксис (комментарии)» . Проверено 6 апреля 2017 .
  50. ^ a b «Базовый синтаксис Python 3» . Проверено 25 февраля 2019 . Тройные кавычки рассматриваются как обычные строки, за исключением того, что они могут занимать несколько строк. Под обычными строками я подразумеваю, что если они не назначены переменной, они будут немедленно собраны мусором, как только этот код будет выполнен. следовательно, интерпретатор не игнорирует их так же, как #a comment.
  51. ^ «Совет Python: вы можете использовать многострочные строки как многострочные комментарии» , 11 сентября 2011 г., Гвидо ван Россум
  52. ^ Талмейдж, Рональд Р. (1999). Microsoft SQL Server 7 . Прима Паблишинг. ISBN 978-0-7615-1389-6.
  53. ^ "Справочное руководство по MySQL 8.0" . Корпорация Oracle . Проверено 2 января 2020 года .
  54. ^ «SQL в понимании SQLite» . Консорциум SQLite . Проверено 2 января 2020 года .
  55. ^ «Документация по PostgreSQL 10.11» . Группа глобального развития PostgreSQL . Проверено 2 января 2020 года .
  56. ^ «Справочник Oracle® Database SQL» . Корпорация Oracle . Проверено 2 января 2020 года .
  57. ^ Андресс, Мэнди (2003). Выживание в безопасности: как интегрировать людей, процессы и технологии . CRC Press. ISBN 978-0-8493-2042-2.

Дальнейшее чтение [ править ]

  • Мовшовиц-Аттиас, Дана и Коэн, Уильям В. (2013) Модели естественного языка для прогнозирования комментариев к программированию . В Ассоциации компьютерной лингвистики (ACL), 2013.

Внешние ссылки [ править ]

  • Как писать комментарии Дениса Круковского
  • Документация по исходному коду в виде интерактивного руководства пользователя от PTLogica
  • Как писать комментарии для инструмента Javadoc
  • Doxygen , система документации для C, C ++, Java, Objective-C, Python, IDL и в некоторой степени PHP, C # и D