Комментарий (компьютерное программирование)

Комментарии в разметке Википедии см. в разделах Help:Wiki markup § Форматирование символов и WP:COMMENT .

"/*" и "*/" перенаправляются сюда. Информацию об их использовании в сводках редактирования Википедии см. в разделе «Справка:Редактировать сводку § Редактирование раздела» .

Иллюстрация исходного кода Java с комментариями пролога , выделенными красным , а встроенными комментариями — зеленым . Код программы выделен синим цветом .

В компьютерном программировании комментарий — это понятное программисту объяснение или аннотация в исходном коде программы компьютерной . Они добавляются с целью облегчить понимание исходного кода людьми и обычно игнорируются компиляторами и интерпретаторами . Синтаксис комментариев в разных языках программирования значительно различается.

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

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

Обзор

Комментарии обычно форматируются либо как блочные комментарии (также называемые комментариями пролога или комментариями потока ), либо как строчные комментарии (также называемые встроенными комментариями ).

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

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

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

Использование

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

Планирование и проверка

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

/* loop backwards through all elements returned by the server 
(they should be processed chronologically)*/
for (i = (numElementsReturned - 1); i >= 0; i--) {
    /* process each element's data */
    updatePattern(i, returnedElements[i]);
}

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

Описание кода

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

«Не документируйте плохой код – перепишите его».

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

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

' Second variable dim because of server errors produced when reuse form data. No
' documentation available on server behavior issue, so just coding around it.
vtx = server.mappath("local settings")

Алгоритмическое описание

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

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

 list = [f (b), f (b), f (c), f (d), f (a), ...];
 // Need a stable sort. Besides, the performance really does not matter.
 insertion_sort (list);

Включение ресурсов

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

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

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

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

Метаданные

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

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

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

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

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

Отладка

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

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

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

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

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

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

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

Расширение синтаксиса

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

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

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

Два примера такого указания переводчику:

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

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

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-
print("Testing")

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

switch (command) {
    case CMD_SHOW_HELP_AND_EXIT:
      do_show_help();
      /* Fall thru */
    case CMD_EXIT:
      do_exit();
      break;
    case CMD_OTHER:
      do_other();
      break;
    /* ... etc. ... */
  }

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

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

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

Снятие стресса

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

Нормативные взгляды

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

Нужны комментарии

Эксперты имеют разные точки зрения на то, уместны ли комментарии в исходном коде и если да, то когда. Некоторые утверждают, что исходный код должен быть написан с небольшим количеством комментариев, исходя из того, что исходный код должен быть понятным и самодокументированным . Другие предлагают, чтобы код был подробно комментирован (нередко более 50% непробельных символов в исходном коде содержатся в комментариях).

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

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

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

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

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

String s = "Wikipedia"; /* Assigns the value "Wikipedia" to the variable s. */

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

Стили

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

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

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

/*
     This is the comment body.
     Variation One.
*/

/***************************\
*                           *
* This is the comment body. *
* Variation Two.            *
*                           *
\***************************/

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

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

 /* This is the style recommended by Holub for C and C++.
  * It is demonstrated in ''Enough Rope'', in rule 29.
  */

 /* This is another way to do it, also in C.
 ** It is easier to do in editors that do not automatically indent the second
 ** through last lines of the comment one space from the first.
 ** It is also used in Holub's book, in rule 31.
 */

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

Комментарии к строке

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

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

// -------------------------
// This is the comment body.
// -------------------------

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

print $s . "\n";     # Add a newline character after printing

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

Теги

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

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

• BUG, DEBUG — известная ошибка , которую следует исправить.
• FIXME — надо исправить.
• HACK, BODGE, KLUDGE — обходной путь.
• TODO — что-то, что нужно сделать.
• ПРИМЕЧАНИЕ — используется для выделения особо заметных ошибок .
• UNDONE — разворот или «откат» предыдущего кода.
• XXX — предупреждать других программистов о проблемном или ошибочном коде.

Примеры

Сравнение

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

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

Есть

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

Например:

  -- the air traffic controller task takes requests for takeoff and landing
   task type Controller (My_Runway: Runway_Access) is
      -- task entries for synchronous message passing
      entry Request_Takeoff (ID: in Airplane_ID; Takeoff: out Runway_Access);
      entry Request_Approach(ID: in Airplane_ID; Approach: out Runway_Access);
   end Controller;

АПЛ

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

Например:

⍝ Now add the numbers:
c←a+b ⍝ addition

В диалектах, имеющих ⊣ («левый») и ⊢ («правильные») примитивы, комментарии часто могут быть внутри или отдельными операторами в виде игнорируемых строк:

d←2×c ⊣'where'⊢ c←a+ 'bound'⊢ b

AppleScript

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

(*
This program displays a greeting.
*)
on greet(myGreeting)
     display dialog myGreeting & " world!"
end greet

-- Show the greeting
greet("Hello")

БАЗОВЫЙ

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

10 REM This BASIC program shows the use of the PRINT and GOTO Statements.
15 REM It fills the screen with the phrase "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:

Public Class Form1
    Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
        ' The following code is executed when the user
        ' clicks the button in the program's window.
        rem comments still exist.

        MessageBox.Show("Hello, World") 'Show a pop-up window with a greeting
    End Sub
End Class

С

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

 /*
  * Check if we are over our maximum process limit, but be sure to
  * exclude root. This is needed to make it possible for login and
  * friends to set the per-user process limit to something lower
  * than the amount of processes root is running. -- Rik
  */
 if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur
     && !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE))
     goto bad_fork_free;

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

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

static Edge edge_any(Node n, Node m) {
    // Returns whether any edge is between nodes $n and $m.
    Edge e;
    for (e=n->edges; e; e=e->next) {
        if (e->dst == m) {
/*********/ return e; } }
    for (e=m->edges; e; e=e->next) {
        if (e->dst == n) {
    /*****/ break; } }
    return e; }

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

Конфигурация Cisco IOS и IOS-XE

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

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

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

! Paste the text below to reroute traffic manually
config t
int gi0/2
no shut
ip route 0.0.0.0 0.0.0.0 gi0/2 name ISP2
no ip route 0.0.0.0 0.0.0.0 gi0/1 name ISP1
int gi0/1
shut
exit

КолдФьюжн

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

Такие комментарии являются вложенными.

 <!--- This prints "Hello World" to the browser.
   <!--- This is a comment used inside the first one.
   --->
 --->
 <cfoutput>
   Hello World<br />
 </cfoutput>

Д

D использует комментарии в стиле C++, а также вложенные многострочные комментарии в стиле D, которые начинаются с '/+' и заканчиваются '+/'.

// This is a single-line comment.
/* This is a multiline comment.

*/
/+ This is a
  /+ nested +/
    comment +/

Фортран IV

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

C
C Lines that begin with 'C' (in the first or 'comment' column) are comments
C
      WRITE (6,610)
  610 FORMAT(12H HELLO WORLD)
      END

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

Фортран 90

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

!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!* All characters after an exclamation mark are considered as comments *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
program comment_test
    print '(A)', 'Hello world' ! Fortran 90 introduced the option for inline comments.
end program

Хаскелл

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

{- this is a comment
on more lines -}
-- and this is a comment on one line
putStrLn "Wikipedia"  -- this is another comment

Haskell также предоставляет грамотный метод программирования комментариев, известный как «Птичий стиль». При этом все строки, начинающиеся с >, интерпретируются как код, все остальное считается комментарием. Еще одним требованием является то, что вы всегда должны оставлять пустую строку до и после блока кода:

In Bird-style you have to leave a blank before the code.

> fact :: Integer -> Integer
> fact 0 = 1
> fact (n+1) = (n+1) * fact n

And you have to leave a blank line after the code as well.

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

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

позже в

% the LaTeX source file
The \verb|fact n| function call computes $n!$ if $n\ge 0$, here is a definition:\\
\begin{code}
fact :: Integer -> Integer
fact 0 = 1
fact (n+1) = (n+1) * fact n
\end{code}
Here more explanation using \LaTeX{} markup

Ява

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

/**
 * This is a block comment in Java.
 * The setToolTipText method registers the text to display in a tool tip.
 * The text is displayed when the cursor lingers over the component.
 *
 * @param text  The string to be displayed.  If 'text' is null,
 *              the tool tip is turned off for this component.
 */
public void setToolTipText(String text) {
    // This is an inline comment in Java. TODO: Write code for this method.
}

JavaScript

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

// A single line JavaScript comment
var iNum = 100;
var iTwo = 2; // A comment at the end of line
/*
multi-line
JavaScript comment
*/

Два

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

Например:

--[[A multi-line
long comment
]]
print(20)   -- print the result

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

--[[
print(10)
--]]
-- no action (commented out)

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

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

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

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

МАТЛАБ

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

% These are the derivatives for each term
d = [0 -1 0];

%{
  %{
    (Example of a nested comment, indentation is for cosmetics (and ignored).)
  %}
  We form the sequence, following the Taylor formula.
  Note that we're operating on a vector.
%}
seq = d .* (x - c).^n ./(factorial(n))

% We add-up to get the Taylor approximation
approx = sum(seq)

Nim

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

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

## Documentation of the module *ReSTructuredText* and **MarkDown**
# This is a comment, but it is not a documentation comment.

type Kitten = object  ## Documentation of type
  age: int  ## Documentation of field

proc purr(self: Kitten) =
  ## Documentation of function
  echo "Purr Purr"  # This is a comment, but it is not a documentation comment.

# This is a comment, but it is not a documentation comment.

OCaml

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

codeLine(* comment level 1(*comment level 2*)*)

Паскаль, Дельфи

В Pascal и Delphi комментарии разделяются символом '{ ... }'. Строки комментариев также могут начинаться с '\\' . В качестве альтернативы для компьютеров, которые не поддерживают эти символы, допускается использование символов «(* ... *)».

В Никлауса Вирта более современном семействе языков (включая Modula-2 и Oberon ) комментарии разделяются символом «(* ... *)».

Например:

(* test diagonals *)
columnDifference := testColumn - column;
if (row + columnDifference = testRow) or
    .......

Комментарии могут быть вложенными. // может быть включено в {}, а {} может быть включено в (**).

Перл

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

# A simple example
# 
my $s = "Wikipedia"; # Sets the variable s to "Wikipedia".
print $s . "\n";     # Add a newline character after printing

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

=item Pod::List-E<gt>new()

Create a new list object. Properties may be specified through a hash
reference like this:

  my $list = Pod::List->new({ -start => $., -indent => 4 });

See the individual methods/properties for details.

=cut

sub new {
    my $this = shift;
    my $class = ref($this) || $this;
    my %params = @_;
    my $self = {%params};
    bless $self, $class;
    $self->initialize();
    return $self;
}

Р

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

# This is a comment
print("This is not a comment")  # This is another comment

Раку

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

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

#`{{ "commenting out" this version 
toggle-case(Str:D $s)

Toggles the case of each character in a string:

  my Str $toggled-string = toggle-case("mY NAME IS mICHAEL!");

}}

sub toggle-case(Str:D $s) #`( this version of parens is used now ){
    ...
}

PHP

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

Начиная с PHP 8, знак # может означать комментарий только в том случае, если за ним сразу не следует '['. В противном случае это будет означать атрибут функции, который действует до ']':

/**
 * This class contains a sample documentation.
 * 
 * @author Unknown
 */
#[Attribute]
class MyAttribute {
    const VALUE = 'value';
    // This is an inline comment. It starts with '//', like in C++.
    private $value;
    # This is a Unix-style inline comment, which starts with '#'.
    public function __construct($value = null) {
        $this->value = $value;
    }
    /*
    This is a multiline comment.

    These comments cannot be nested.
    */

}

PowerShell

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

# Single line comment
Write-Host "Hello, World!"

<# Multi
   Line
   Comment #>

Write-Host "Goodbye, world!"

Питон

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

# This program prints "Hello World" to the screen
print("Hello World!")  # Note the new syntax

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

"""
Assuming this is file mymodule.py, then this string, being the
first statement in the file, will become the "mymodule" module's
docstring when the file is imported.
"""

class MyClass:
    """The class's docstring"""

    def my_method(self):
        """The method's docstring"""

def my_function():
    """The function's docstring"""

Руби

Встроенные комментарии в Ruby начинаются с символа #.

Чтобы создать многострочный комментарий, необходимо поместить «=begin» в начале строки, а затем все, что начинается с «=end», игнорируется. Включение пробела после знака равенства в этом случае приводит к синтаксической ошибке.

puts "This is not a comment"

# this is a comment

puts "This is not a comment"

=begin

whatever goes in these lines

is just for the human reader

=end

puts "This is not a comment"

SQL

Стандартные комментарии в SQL состоят только из одной строки и состоят из двух тире:

-- This is a single line comment
-- followed by a second line
SELECT COUNT(*)
       FROM Authors
       WHERE Authors.name = 'Smith'; -- Note: we only want 'smith'
                                     -- this comment appears after SQL code

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

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

Быстрый

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

// This is a comment.

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

/* This is also a comment
 but is written over multiple lines. */

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

/* This is the start of the first multiline comment.
 /* This is the second, nested multiline comment. */
 This is the end of the first multiline comment. */

XML (или HTML)

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

<!--

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

-->

Например,

<!-- select the context here -->
<param name="context" value="public" />

Для совместимости с SGML внутри комментариев не допускается строка «--» (двойной дефис).

Проблемы безопасности

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

См. также

• Docstring — комментарий особого типа, который анализируется и сохраняется на протяжении всего времени выполнения программы.
• Шебанг , использование #! как директива интерпретатора в сценариях Unix-подобных систем
• HTML-тег комментария
• Грамотное программирование , альтернативная парадигма документации.
• Синтаксис комментариев на различных языках программирования
• КОММЕНТАРИЙ (директива CONFIG.SYS)
• REM (директива CONFIG.SYS)

Дальнейшее чтение

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

Внешние ссылки

• Как писать комментарии Денис Круковский
• Документация исходного кода в виде действующего руководства пользователя от PTLogica
• Как писать комментарии для инструмента Javadoc