В программировании комментарий — это понятное человеку объяснение или аннотация в исходном коде компьютерной программы . Они добавляются с целью сделать исходный код более понятным для человека и обычно игнорируются компиляторами и интерпретаторами . [1] [2] Синтаксис комментариев в различных языках программирования значительно различается.
Комментарии иногда также обрабатываются различными способами для создания документации, внешней по отношению к исходному коду, с помощью генераторов документации или используются для интеграции с системами управления исходным кодом и другими видами внешних инструментов программирования .
Гибкость, обеспечиваемая комментариями, допускает широкую степень вариативности, но формальные соглашения по их использованию обычно являются частью руководств по стилю программирования .
Комментарии обычно форматируются как блочные комментарии (также называемые прологовыми комментариями или потоковыми комментариями ) или строчные комментарии (также называемые встроенными комментариями ). [3]
Блок комментариев ограничивает область исходного кода, которая может охватывать несколько строк или часть одной строки. Эта область указывается начальным и конечным разделителями . Некоторые языки программирования (например, MATLAB ) позволяют рекурсивно вкладывать друг в друга блоки комментариев, но другие (например, Java ) этого не делают. [4] [5] [6]
Строчные комментарии либо начинаются с разделителя комментариев и продолжаются до конца строки, либо, в некоторых случаях, начинаются с определенного столбца (смещение строки символов) в исходном коде и продолжаются до конца строки. [6]
Некоторые языки программирования используют как блочные, так и строчные комментарии с различными разделителями комментариев. Например, в C++ есть блочные комментарии, разделенные /*и , */которые могут охватывать несколько строк, и строчные комментарии, разделенные //. Другие языки поддерживают только один тип комментариев. Например, комментарии Ada являются строчными комментариями: они начинаются с --и продолжаются до конца строки. [6]
Как лучше всего использовать комментарии, является предметом спора; разные комментаторы предлагают различные, а иногда и противоположные точки зрения. [7] [8] Существует много разных способов написания комментариев, и многие комментаторы предлагают противоречивые советы. [8]
Комментарии могут использоваться как форма псевдокода для описания намерений перед написанием фактического кода. В этом случае они должны объяснять логику кода, а не сам код.
/* цикл в обратном порядке по всем элементам, возвращаемым сервером (они должны обрабатываться в хронологическом порядке)*/ for ( i = ( numElementsReturned - 0 ); i >= 1 ; i -- ) { /* обработка данных каждого элемента */ updatePattern ( i , returnsElements [ i ]); } Если оставить этот тип комментария, это упрощает процесс проверки, позволяя напрямую сравнивать код с предполагаемыми результатами. Распространенная логическая ошибка заключается в том, что код, который легко понять, делает то, что он должен делать.
Комментарии могут использоваться для обобщения кода или для объяснения намерений программиста. Согласно этой школе мысли, пересказ кода на простом английском языке считается излишним; необходимость в повторном объяснении кода может быть признаком того, что он слишком сложен и его следует переписать, или что название неудачное.
Комментарии также могут использоваться для объяснения того, почему блок кода не соответствует соглашениям или лучшим практикам. Это особенно касается проектов, требующих очень мало времени на разработку или исправление ошибок. Например:
' Вторая переменная dim из-за ошибок сервера, возникающих при повторном использовании данных формы. ' Документация по проблеме поведения сервера отсутствует, поэтому просто кодируем вокруг нее. vtx = server . mappath ( "local settings" ) Иногда исходный код содержит новое или примечательное решение конкретной проблемы. В таких случаях комментарии могут содержать объяснение методологии. Такие объяснения могут включать диаграммы и формальные математические доказательства. Это может представлять собой объяснение кода, а не разъяснение его намерений; но другие, которым поручено поддерживать кодовую базу, могут посчитать такое объяснение решающим. Это может быть особенно верно в случае узкоспециализированных проблемных областей; или редко используемых оптимизаций, конструкций или вызовов функций. [11]
Например, программист может добавить комментарий, чтобы объяснить, почему была выбрана сортировка вставкой вместо быстрой сортировки , поскольку первая, в теории, медленнее второй. Это можно записать следующим образом:
list = [ f ( b ), f ( b ), f ( c ), f ( d ), f ( a ), ... ] ; // Нужна стабильная сортировка. К тому же производительность на самом деле не имеет значения. insertion_sort ( list ); Логотипы , диаграммы и блок-схемы, состоящие из художественных конструкций ASCII, могут быть вставлены в исходный код, отформатированный как комментарий. [12] Кроме того, уведомления об авторских правах могут быть встроены в исходный код как комментарии. Двоичные данные также могут быть закодированы в комментариях с помощью процесса, известного как двоично-текстовое кодирование , хотя такая практика встречается редко и обычно относится к внешним файлам ресурсов.
Следующий фрагмент кода представляет собой простую диаграмму ASCII, изображающую поток процесса для скрипта системного администрирования , содержащегося в файле скрипта Windows, работающем под управлением Windows Script Host . Хотя раздел, помечающий код, отображается как комментарий, сама диаграмма фактически отображается в разделе XML CDATA , который технически считается отличным от комментариев, но может служить аналогичным целям. [13]
<!-- начало: 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> Хотя эту идентичную диаграмму можно было бы легко включить в качестве комментария, пример иллюстрирует один случай, когда программист может решить не использовать комментарии как способ включения ресурсов в исходный код. [13]
Комментарии в компьютерной программе часто хранят метаданные о файле программы.
В частности, многие специалисты по сопровождению программного обеспечения размещают в комментариях инструкции по отправке, чтобы помочь людям, читающим исходный код этой программы, отправлять любые внесенные ими улучшения специалисту по сопровождению.
Другие метаданные включают в себя: имя создателя исходной версии программного файла и дату создания первой версии, имя текущего сопровождающего программы, имена других людей, которые редактировали программный файл до настоящего момента, URL-адрес документации о том, как использовать программу, название лицензии на программное обеспечение для этого программного файла и т. д.
Когда алгоритм в каком-либо разделе программы основан на описании в книге или другом источнике, комментарии могут использоваться для указания номера страницы и названия книги или запроса комментариев или другой ссылки.
Распространенной практикой разработчиков является комментирование фрагмента кода, то есть добавление синтаксиса комментария, в результате чего этот блок кода становится комментарием, так что он не будет выполняться в конечной программе. Это может быть сделано для исключения определенных фрагментов кода из конечной программы или (чаще) может быть использовано для поиска источника ошибки. Систематически комментируя и запуская части программы, можно определить источник ошибки, что позволит исправить ее.
Многие IDE позволяют быстро добавлять или удалять такие комментарии с помощью отдельных опций меню или комбинаций клавиш. Программисту нужно только отметить часть текста, которую он хочет (не)комментировать, и выбрать соответствующую опцию.
Инструменты программирования иногда хранят документацию и метаданные в комментариях. [14] Они могут включать позиции вставки для автоматического включения заголовочного файла, команды для установки режима подсветки синтаксиса файла , [15] или номер ревизии файла . [16] Эти комментарии функционального управления также обычно называются аннотациями . Хранение документации в комментариях исходного кода считается одним из способов упрощения процесса документирования, а также повышения вероятности того, что документация будет обновляться с учетом изменений в коде. [17]
Примерами генераторов документации являются программы Javadoc для использования с Java , Ddoc для D , Doxygen для C , C++ , Java, IDL , Visual Expert для PL/SQL , Transact-SQL , PowerBuilder и PHPDoc для PHP . Формы docstring поддерживаются Python , Lisp , Elixir и Clojure . [18]
C# , F# и Visual Basic .NET реализуют похожую функцию, называемую «XML-комментарии», которые считываются IntelliSense из скомпилированной сборки .NET . [19]
Иногда элементы синтаксиса, изначально предназначенные для комментариев, переназначаются для передачи дополнительной информации программе, например, « условные комментарии ». Такие «горячие комментарии» могут быть единственным практическим решением, которое поддерживает обратную совместимость, но широко рассматриваются как халтура . [20]
Одним из конкретных примеров являются docblocks , которые являются специально отформатированными комментариями, используемыми для документирования определенного сегмента кода. Это делает формат DocBlock независимым от целевого языка (при условии, что он поддерживает комментарии); однако это также может привести к появлению множественных или несогласованных стандартов.
Бывают случаи, когда обычные символы комментариев используются для создания специальной директивы для редактора или интерпретатора.
Вот два примера такого руководства переводчиком:
#!— используется в первой строке скрипта для указания на используемый интерпретатор.Приведенный ниже скрипт для Unix-подобной системы демонстрирует оба варианта использования:
#!/usr/bin/env python3 # -*- кодировка: UTF-8 -*- печать ( "Тестирование" )Нечто похожее происходит с использованием комментариев в языке C для сообщения компилятору о том, что «провал» по умолчанию в операторе case был сделан намеренно:
переключатель ( команда ) { случай CMD_SHOW_HELP_AND_EXIT : do_show_help (); /* Провал */ случай CMD_EXIT : do_exit (); перерыв ; случай 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 подойдет для вводного текста, предназначенного для обучения начинающих программистов:
String s = "Wikipedia" ; /* Присваивает значение "Wikipedia" переменной s. */ Однако этот уровень детализации не будет уместен в контексте производственного кода или других ситуаций, в которых задействованы опытные разработчики. Такие элементарные описания не соответствуют руководству: «Хорошие комментарии... проясняют намерение». [10] Кроме того, для профессиональных сред кодирования уровень детализации обычно хорошо определен, чтобы соответствовать конкретным требованиям производительности, определяемым бизнес-операциями. [31]
Существует множество стилистических альтернатив при рассмотрении того, как комментарии должны отображаться в исходном коде. Для более крупных проектов, в которых задействована команда разработчиков, стили комментариев либо согласовываются до начала проекта, либо развиваются в соответствии с соглашением или необходимостью по мере роста проекта. Обычно программисты предпочитают стили, которые являются последовательными, не создающими помех, легко модифицируемыми и трудно нарушаемыми. [34]
Следующие фрагменты кода на языке C демонстрируют лишь небольшой пример того, как комментарии могут различаться стилистически, при этом передавая одну и ту же базовую информацию:
/* Это тело комментария. Вариант первый. *//******************************\ * * * Это текст комментария. * * Вариант два. * * * \******************************/Такие факторы, как личные предпочтения, гибкость инструментов программирования и другие соображения, как правило, влияют на стилистические варианты, используемые в исходном коде. Например, вариант 2 может быть непопулярным среди программистов, у которых нет редакторов исходного кода , которые могут автоматизировать выравнивание и визуальное оформление текста в комментариях.
Консультант по программному обеспечению и технологический комментатор Аллен Холуб [35] — один из экспертов, который выступает за выравнивание левого края комментариев: [36]
/* Это стиль, рекомендованный Голубом для C и C++. * Он продемонстрирован в ''Enough Rope'', в правиле 29. */ /* Это еще один способ сделать это, также на языке C. ** Это проще сделать в редакторах, которые не делают автоматически отступ со второй ** по последнюю строку комментария на один пробел от первой. ** Это также используется в книге Голуба, в правиле 31. */Использование /* и */ в качестве разделителей комментариев блоков было унаследовано от PL/I в языке программирования B, непосредственном предшественнике языка программирования C. [37]
В строковых комментариях обычно используется произвольный разделитель или последовательность токенов для обозначения начала комментария и символ новой строки для обозначения конца комментария.
В этом примере весь текст от символов ASCII // до конца строки игнорируется.
// ------------------------- // Это текст комментария. // -------------------------Часто такой комментарий должен начинаться с самого левого края и распространяться на всю строку. Однако во многих языках также возможно поместить комментарий в командную строку, чтобы добавить комментарий к ней – как в этом примере Perl:
print $s . "\n" ; # Добавить символ новой строки после печати Если язык допускает как строчные, так и блочные комментарии, команды программистов могут принять решение об их различном использовании: например, строчные комментарии только для второстепенных комментариев и блочные комментарии для описания абстракций более высокого уровня.
Программисты могут использовать неформальные теги в комментариях для помощи в индексировании общих проблем. Затем их можно будет искать с помощью обычных инструментов программирования, таких как утилита Unix grep , или даже с помощью подсветки синтаксиса в текстовых редакторах . Иногда их называют «кодовыми тегами» [38] [39] или «токенами», и инструменты разработки могут даже помочь вам в перечислении всех из них. [40]
Такие теги сильно различаются, но могут включать в себя:
Типографские соглашения для указания комментариев сильно различаются. Кроме того, отдельные языки программирования иногда предоставляют уникальные варианты.
В языке программирования Ada для обозначения комментария до конца строки используется символ «--».
Например:
-- задача авиадиспетчера принимает запросы на взлет и посадку тип задачи Controller ( My_Runway : Runway_Access ) -- записи задач для синхронной передачи сообщений 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 используется ⍝для обозначения комментария до конца строки.
Например:
⍝ Теперь складываем числа: c ← a + b ⍝ сложение В диалектах, имеющих примитивы ⊣(«left») и ⊢(«right»), комментарии часто могут находиться внутри или отдельно от операторов в виде игнорируемых строк:
d ← 2 × c ⊣ 'где' ⊢ c ← a + 'связан' ⊢ b В этом разделе кода AppleScript показаны два стиля комментариев, используемых в этом языке.
(* Эта программа отображает приветствие. *) on greet ( myGreeting ) отображает диалоговое окно myGreeting & " world!" end greet-- Показать приветственное приветствие ( "Привет" )В этом классическом фрагменте кода раннего BASIC ключевое слово REM ( «Remark» ) используется для добавления комментариев.
10 REM Эта программа BASIC демонстрирует использование операторов 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:
Public Class Form1 Private Sub Button1_Click ( sender As Object , e As EventArgs ) Handles Button1 . Click ' Следующий код выполняется, когда пользователь ' нажимает кнопку в окне программы. rem комментарии все еще существуют. MessageBox . Show ( "Hello, World" ) 'Показать всплывающее окно с приветствием End Sub End Class Этот фрагмент кода C демонстрирует использование прологового комментария или «блочного комментария» для описания цели условного оператора . Комментарий объясняет ключевые термины и концепции и включает короткую подпись программиста, который написал код.
/* * Проверяем, не превысили ли мы максимальный лимит процессов, но обязательно * исключим root. Это необходимо, чтобы дать возможность логину и * друзьям установить лимит процессов для каждого пользователя на что-то меньшее, * чем количество процессов, запущенных root. -- Rik */ if ( atomic_read ( & p -> user -> processes ) >= p -> rlim [ RLIMIT_NPROC ]. rlim_cur && ! able ( CAP_SYS_ADMIN ) && ! able ( CAP_SYS_RESOURCE )) goto bad_fork_free ; Начиная с C99 также стало возможным использовать синтаксис // из C++, обозначающий однострочный комментарий.
Наличие блочных комментариев позволяет наглядно отмечать структурные нарушения, т.е. допустимые нарушения правила структурного программирования «единственный вход/единственный выход », как в следующем примере:
static Edge edge_any ( Node n , Node m ) { // Возвращает, есть ли ребро между узлами $n и $m. Edge e ; for ( e = n -> sides ; e ; e = e -> next ) { if ( e -> dst == m ) { /*********/ return e ; } } for ( e = m -> sides ; e ; e = e -> next ) { if ( e -> dst == n ) { /*****/ break ; } } return e ; } Во многих языках, где нет блочного комментария, например, awk , вместо этого можно использовать последовательности разделителей операторов, например ;. Но это невозможно в языках, использующих отступы как жесткое указание на предполагаемую блочную структуру, например, Python .
Восклицательный знак ( ! ) может использоваться для обозначения комментариев в режиме конфигурации маршрутизатора Cisco, однако такие комментарии не сохраняются в энергонезависимой памяти (которая содержит startup-config) и не отображаются командой «show run». [41] [42]
Можно вставить понятный человеку контент, который фактически является частью конфигурации и может быть сохранен в стартовой конфигурации NVRAM с помощью:
! Вставьте текст ниже, чтобы вручную перенаправить трафикконфигурация тцелочисленный gi0/2нет затвораip маршрут 0.0.0.0 0.0.0.0 gi0/2 имя ISP2нет ip маршрута 0.0.0.0 0.0.0.0 gi0/1 имя ISP1целочисленный gi0/1закрытьВыходColdFusion использует комментарии, похожие на комментарии HTML , но вместо двух тире он использует три. Эти комментарии улавливаются движком ColdFusion и не выводятся в браузер.
Такие комментарии являются вложенными.
<!--- Это выводит "Hello World" в браузер. <!--- Это комментарий, используемый внутри первого. ---> ---> <cfoutput> Hello World < br /> </cfoutput>D использует комментарии в стиле C++, а также вложенные многострочные комментарии в стиле D, которые начинаются с «/+» и заканчиваются на «+/».
// Это однострочный комментарий. /* Это многострочный комментарий.*/ /+ Это /+ вложенный +/ комментарий +/Этот фрагмент кода Fortran IV демонстрирует, как комментарии используются в этом языке, который очень ориентирован на столбцы. Буква "C" в столбце 1 заставляет всю строку рассматриваться как комментарий.
C C Строки, начинающиеся с «C» (в первом столбце или столбце «комментарий»), являются комментариями C WRITE ( 6 , 610 ) 610 FORMAT ( 12 H HELLO WORLD ) END Обратите внимание, что столбцы строки в противном случае рассматриваются как четыре поля: с 1 по 5 — поле метки, 6 приводит к тому, что строка рассматривается как продолжение предыдущего оператора, а объявления и операторы располагаются с 7 по 72.
Этот фрагмент кода на языке Fortran демонстрирует, как используются комментарии в этом языке, при этом сами комментарии описывают основные правила форматирования.
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! * Все символы после восклицательного знака считаются комментариями * !* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * program comment_test print '(A)' , 'Hello world' ! В Fortran 90 появилась возможность для встроенных комментариев. end program Строчные комментарии в Haskell начинаются с «--» (два дефиса) до конца строки, а многострочные комментарии начинаются с «{-» и заканчиваются «-}».
{- это комментарий к нескольким строкам -} -- а это комментарий к одной строке putStrLn "Wikipedia" -- это еще один комментарий Haskell также предоставляет грамотный метод программирования комментариев, известный как «Bird Style». [43] В нем все строки, начинающиеся с >, интерпретируются как код, все остальное считается комментарием. Еще одно дополнительное требование — всегда оставлять пустую строку до и после блока кода:
В стиле Bird перед кодом необходимо оставить пробел.> факт :: Целое число -> Целое число > факт 0 = 1 > факт ( n + 1 ) = ( n + 1 ) * факт n И после кода тоже нужно оставить пустую строку.Грамотное программирование также может быть выполнено в Haskell, с использованием LaTeX . Окружение кода может быть использовано вместо стиля Ричарда Берда: В стиле LaTeX это эквивалентно приведенному выше примеру, окружение кода может быть определено в преамбуле LaTeX. Вот простое определение:
\usepackage { verbatim } \newenvironment { code }{ \verbatim }{ \endverbatim }позже в
% исходный файл LaTeX Вызов
функции \verb |fact n| вычисляет $ n ! $ если $ n \ge 0 $ , вот определение: \\ \begin { code } fact :: Integer -> Integer fact 0 = 1 fact ( n + 1 ) = ( n + 1 ) * fact n \end { code }
Вот более подробное объяснение с использованием разметки \LaTeX {} Этот фрагмент кода Java показывает блочный комментарий, используемый для описания setToolTipTextметода. Форматирование соответствует стандартам Sun Microsystems Javadoc . Комментарий предназначен для чтения процессором Javadoc.
/** * Это блочный комментарий в Java. * Метод setToolTipText регистрирует текст для отображения во всплывающей подсказке. * Текст отображается, когда курсор задерживается на компоненте. * * @param text Строка для отображения. Если 'text' равен null, * всплывающая подсказка для этого компонента отключена. */ public void setToolTipText ( String text ) { // Это встроенный комментарий в Java. TODO: Написать код для этого метода. } JavaScript использует // для предшествования комментариям и /* */ для многострочных комментариев.
// Однострочный комментарий JavaScript var iNum = 100 ; var iTwo = 2 ; // Комментарий в конце строки /* многострочный комментарий JavaScript */ Язык программирования Lua использует двойные дефисы, --, для однострочных комментариев аналогично языкам Ada , Eiffel , Haskell , SQL и VHDL . Lua также имеет блочные комментарии, которые начинаются с --[[и продолжаются до закрывающего]]
Например:
--[[Многострочный длинный комментарий ]] print ( 20 ) -- распечатать результатРаспространенный метод комментирования фрагмента кода [44] заключается в заключении кода между --[[и --]], как показано ниже:
--[[ print(10) --]] -- никаких действий (закомментировано)В этом случае можно повторно активировать код, добавив один дефис в первую строку:
---[[ печать ( 10 ) --]] --> 10В первом примере --[[в первой строке начинается длинный комментарий, а два дефиса в последней строке все еще находятся внутри этого комментария. Во втором примере последовательность ---[[начинает обычный однострочный комментарий, так что первая и последняя строки становятся независимыми комментариями. В этом случае printнаходится за пределами комментариев. В этом случае последняя строка становится независимым комментарием, так как начинается с --.
Длинные комментарии в Lua могут быть более сложными, о чем вы можете прочитать в разделе «Длинные строки» книги Программирование в Lua .
В языке программирования MATLAB символ '%' обозначает однострочный комментарий. Многострочные комментарии также доступны через скобки %{ и %} и могут быть вложенными, например
% Это производные для каждого члена d = [ 0 - 1 0 ]; %{ %{ ( Пример вложенного комментария, отступы для косметики (и игнорируются).) %} Формируем последовательность , следуя формуле Тейлора . Обратите внимание , что мы работаем с вектором . % } seq = d . * ( x - c ) . ^ n ./ ( factorial ( n ) ) % Складываем, чтобы получить приближение Тейлора approx = sum ( seq ) Nim использует символ '#' для встроенных комментариев. Многострочные блочные комментарии открываются с помощью '#[' и закрываются с помощью ']#'. Многострочные блочные комментарии могут быть вложенными.
Nim также имеет комментарии документации, которые используют смешанную разметку Markdown и ReStructuredText . Встроенные комментарии документации используют '##', а многострочные блочные комментарии документации открываются с помощью '##[' и закрываются с помощью ']##'. Компилятор может генерировать документацию HTML , LaTeX и JSON из комментариев документации. Комментарии документации являются частью абстрактного синтаксического дерева и могут быть извлечены с помощью макросов. [45]
## Документация модуля *ReSTructuredText* и **MarkDown** # Это комментарий, но это не комментарий к документации.тип Котенок = объект ## Документация типа возраст : int ## Документация поля proc purr ( self : Kitten ) = ## Документация функции echo "Purr Purr" # Это комментарий, но это не комментарий документации. # Это комментарий, но не комментарий к документации.OCaml использует вложенные комментарии, что полезно при комментировании блока кода.
codeLine (* уровень комментария 1(*уровень комментария 2*)*)В Pascal и Delphi комментарии разделяются символами '{ ... }'. Строки комментариев также могут начинаться с '\\'. В качестве альтернативы для компьютеров, которые не поддерживают эти символы, разрешены '(* ... *)'. [46]
В более современной семье языков Никлауса Вирта (включая Modula-2 и Oberon ) комментарии разделяются символами «(* ... *)». [47] [48]
Например:
(* проверка диагоналей *) columnDifference := testColumn - column ; if ( row + columnDifference = testRow ) или ....... Комментарии могут быть вложенными. // можно включать в {}, а {} можно включать в (**).
Строчные комментарии в Perl и многих других языках программирования начинаются с символа решетки (#).
# Простой пример # my $s = "Wikipedia" ; # Устанавливает переменную s в "Wikipedia". print $s . "\n" ; # Добавляет символ новой строки после печати Вместо обычной конструкции блочного комментирования Perl использует Plain Old Documentation , язык разметки для грамотного программирования , [49] например: [50]
=item Pod::List-E<gt>новый()Создайте новый объект списка. Свойства могут быть указаны через ссылку на хэш, например: мой $list = Pod::List->new({ -start => $., -indent => 4 });Подробную информацию смотрите в описании отдельных методов/свойств.=вырезатьsub new { мой $this = shift ; мой $class = ref ( $this ) || $this ; мой %params = @_ ; мой $self = { %params }; благослови $self , $class ; $self -> инициализировать (); вернуть $self ; } R поддерживает только встроенные комментарии, начинающиеся с символа решетки (#).
# Это комментарий print ( "Это не комментарий" ) # Это еще один комментарий Raku (ранее называвшийся Perl 6) использует те же строчные комментарии и комментарии документации POD, что и обычный Perl (см. раздел Perl выше), но добавляет настраиваемый тип блочных комментариев: «многострочные / встроенные комментарии». [51]
Они начинаются с символа решетки, за которым следует обратная кавычка, а затем открывающий символ скобок и заканчиваются соответствующим закрывающим символом скобок. [51] Содержимое может не только занимать несколько строк, но и быть встроенным в строку.
#`{{ "закомментирование" этой версии toggle-case(Str:D $s)Переключает регистр каждого символа в строке: моя Str $toggled-string = toggle-case("МЕНЯ ИМЯ МАЙКЛ!");}}sub toggle-case ( Str:D $s ) #`( эта версия скобок используется сейчас ) { ...}Комментарии в PHP могут быть в стиле C++ (как встроенные, так и блочные) или использовать хэши. PHPDoc — это стиль, адаптированный из Javadoc, и является общепринятым стандартом для документирования кода PHP.
Начиная с PHP 8, знак # может означать комментарий только в том случае, если за ним не следует сразу '['. В противном случае он будет означать атрибут функции, который выполняется до ']':
/** * Этот класс содержит пример документации. * * @author Unknown */ #[ Attribute ] class MyAttribute { const VALUE = 'value' ; // Это встроенный комментарий. Он начинается с '//', как в C++. private $value ; # Это встроенный комментарий в стиле Unix, который начинается с '#'. public function __construct ( $value = null ) { $this -> value = $value ; } /* Это многострочный комментарий. Эти комментарии не могут быть вложенными. */}Комментарии в Windows PowerShell
# Однострочный комментарий Write-Host "Hello, World!"<# Многострочный комментарий #>Напишите-Ведущая "Прощай, мир!"Встроенные комментарии в Python используют символ решетки (#), как в двух примерах в этом коде:
# Эта программа выводит на экран сообщение "Hello World!" ( "Hello World!" ) # Обратите внимание на новый синтаксисБлочные комментарии, как определено в этой статье, технически не существуют в Python. [52] Можно использовать голый строковый литерал, представленный строкой в тройных кавычках, [53] но он не игнорируется интерпретатором так же, как комментарий "#". [52] В примерах ниже строки в тройных двойных кавычках действуют таким образом как комментарии, но также обрабатываются как строки документации :
""" Предположим, что это файл mymodule.py, тогда эта строка, будучи первым оператором в файле, станет строкой документации модуля "mymodule" при импорте файла. """class MyClass : """Строка документации класса""" def my_method ( self ): """Строка документации метода""" def my_function (): """Строка документации функции""" Встроенные комментарии в Ruby начинаются с символа #.
Чтобы создать многострочный комментарий, необходимо поместить "=begin" в начало строки, а затем все до "=end", которое начинает строку, будет игнорироваться. Включение пробела после знака равенства в этом случае вызовет синтаксическую ошибку.
ставит "Это не комментарий" # это комментарийставит "Это не комментарий" =начатьчто бы ни значилось в этих строкахпредназначен только для человеческого читателя=конецставит "Это не комментарий" Стандартные комментарии в SQL представляют собой одну строку с двумя тире:
-- Это однострочный комментарий , за которым следует вторая строка SELECT COUNT ( * ) FROM Authors WHERE Authors . name = 'Smith' ; -- Примечание: нам нужно только 'smith' -- этот комментарий появляется после кода SQL В качестве альтернативы синтаксис формата комментариев, идентичный стилю «блочного комментария», используемому в синтаксисе для C и Java, поддерживается Transact-SQL , MySQL , SQLite , PostgreSQL и Oracle . [54] [55] [56] [57] [58]
MySQL также поддерживает комментарии от символа решетки (#) до конца строки.
Однострочные комментарии начинаются с двух косых черт (//):
// Это комментарий.Многострочные комментарии начинаются с косой черты, за которой следует звездочка (/*), и заканчиваются звездочкой, за которой следует косая черта (*/):
/* Это тоже комментарий , но написанный на нескольких строках. */Многострочные комментарии в Swift могут быть вложены в другие многострочные комментарии. Вы пишете вложенные комментарии, начиная блок многострочных комментариев, а затем начиная второй многострочный комментарий внутри первого блока. Затем второй блок закрывается, за ним следует первый блок:
/* Это начало первого многострочного комментария. /* Это второй, вложенный многострочный комментарий. */ Это конец первого многострочного комментария. */Комментарии в формате XML (или HTML) вводятся с помощью
< !--и может распространяться на несколько строк до терминатора,
-->Например,
<!-- выберите контекст здесь --> <param name= "context" value= "public" /> Для совместимости с SGML внутри комментариев не допускается использование строки «--» (двойной дефис).
В интерпретируемых языках комментарии видны конечному пользователю программы. В некоторых случаях, например, в разделах кода, которые «закомментированы», это может представлять уязвимость безопасности . [59]
кавычки обрабатываются как обычные строки, за исключением того, что они могут охватывать несколько строк. Под обычными строками я подразумеваю, что если они не назначены переменной, то они будут немедленно удалены сборщиком мусора, как только этот код выполнится. Следовательно, они не игнорируются интерпретатором так же, как комментарий #a.