В компьютерном программировании комментарий — это понятное программисту объяснение или аннотация в исходном коде компьютерной программы . Они добавляются с целью облегчить понимание исходного кода людьми и обычно игнорируются компиляторами и интерпретаторами . [1] [2] Синтаксис комментариев в разных языках программирования значительно различается.
Комментарии иногда также обрабатываются различными способами для создания документации, внешней по отношению к самому исходному коду, с помощью генераторов документации или используются для интеграции с системами управления исходным кодом и другими видами внешних инструментов программирования .
Гибкость, обеспечиваемая комментариями, допускает широкую степень вариативности, но формальные соглашения по их использованию обычно являются частью руководств по стилю программирования .
Комментарии обычно форматируются либо как блочные комментарии (также называемые комментариями пролога или комментариями потока ), либо как строчные комментарии (также называемые встроенными комментариями ). [3]
Блочные комментарии ограничивают область исходного кода, которая может занимать несколько строк или часть одной строки. Этот регион указывается с начальным и конечным разделителем. Некоторые языки программирования (например, MATLAB ) позволяют рекурсивно вкладывать комментарии блоков друг в друга, но другие (например, Java ) этого не делают. [4] [5] [6]
Комментарии к строке либо начинаются с разделителя комментариев и продолжаются до конца строки, либо, в некоторых случаях, начинаются с определенного столбца (смещения строки символов) в исходном коде и продолжаются до конца строки. [6]
В некоторых языках программирования используются как блочные, так и строковые комментарии с разными разделителями комментариев. Например, в C++ есть блочные комментарии, разделенные значком /*и */которые могут занимать несколько строк, а также строковые комментарии, разделенные //. Другие языки поддерживают только один тип комментариев. Например, комментарии Ada представляют собой комментарии к строке: они начинаются с строки --и продолжаются до ее конца. [6]
Вопрос о том, как лучше всего использовать комментарии, является предметом споров; разные комментаторы высказывали разные, а иногда и противоположные точки зрения. [7] [8] Есть много разных способов написания комментариев, и многие комментаторы дают противоречивые советы. [8]
Комментарии можно использовать как форму псевдокода , чтобы обозначить намерение перед написанием фактического кода. В этом случае следует объяснять логику кода, а не сам код.
/* циклически перебираем все элементы, возвращаемые сервером (они должны обрабатываться в хронологическом порядке)*/ for ( i = ( numElementsReturned - 1 ); i >= 0 ; i -- ) { /* обрабатываем данные каждого элемента */ updatePattern ( i , returnElements [ i ]); } Если оставить комментарий такого типа, это упрощает процесс проверки, позволяя напрямую сравнивать код с намеченными результатами. Распространенной логической ошибкой является то, что простой для понимания код делает то, что должен .
Комментарии могут использоваться для обобщения кода или для объяснения намерений программиста. Согласно этой школе мысли, пересказ кода на простом английском языке считается излишним; необходимость переосмысления кода может быть признаком того, что он слишком сложен и его следует переписать, или что имя выбрано неправильно.
Комментарии также могут использоваться для объяснения того, почему блок кода не соответствует соглашениям или лучшим практикам. Это особенно верно для проектов, требующих очень мало времени на разработку или исправление ошибок. Например:
' Вторая переменная dim из-за ошибок сервера, возникающих при повторном использовании данных формы. Нет доступной документации по проблемам поведения сервера, поэтому просто напишите код. vtx = сервер . Mappath ( «локальные настройки» ) Иногда исходный код содержит новое или заслуживающее внимания решение конкретной проблемы. В таких случаях комментарии могут содержать пояснение методики. Такие объяснения могут включать диаграммы и формальные математические доказательства. Это может представлять собой объяснение кода, а не разъяснение его назначения; но другие, кому поручено поддерживать базу кода, могут найти такое объяснение решающим. Это может быть особенно верно в случае узкоспециализированных проблемных областей; или редко используемые оптимизации, конструкции или вызовы функций. [11]
Например, программист может добавить комментарий, объясняющий, почему была выбрана сортировка вставками вместо быстрой сортировки , поскольку первая теоретически работает медленнее, чем вторая. Это можно было бы записать следующим образом:
список = [ ж ( б ), ж ( б ), ж ( с ), ж ( d ), ж ( а ), ... ] ; // Нужна стабильная сортировка. Кроме того, производительность действительно не имеет значения. вставка_сортировка ( список ); Логотипы , диаграммы и блок-схемы , состоящие из художественных конструкций ASCII, можно вставлять в исходный код в виде комментариев. [12] Кроме того, уведомления об авторских правах могут быть встроены в исходный код в виде комментариев. Двоичные данные также могут быть закодированы в комментариях с помощью процесса, известного как кодирование двоичного текста в текст , хотя такая практика встречается редко и обычно относится к внешним файлам ресурсов.
Следующий фрагмент кода представляет собой простую диаграмму ASCII, изображающую поток процесса для сценария системного администрирования , содержащегося в файле сценария Windows , работающем под хостом сценариев Windows . Хотя раздел, обозначающий код, отображается как комментарий, сама диаграмма фактически отображается в разделе XML CDATA , который технически считается отличным от комментариев, но может служить аналогичным целям. [13]
<!-- начало: wsf_resource_nodes --> <resource id= "ProcessDiagram000" > <![CDATA[ HostApp (Main_process) | V script.wsf (app_cmd) --> ClientApp (async_run, пакетный_процесс) | | 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 . Формы строки документации поддерживаются Python , Lisp , Elixir и Clojure . [18]
C# , F# и Visual Basic .NET реализуют аналогичную функцию, называемую «Комментарии XML», которые считываются IntelliSense из скомпилированной сборки .NET . [19]
Иногда элементы синтаксиса, которые изначально были предназначены для комментариев, переназначаются для передачи в программу дополнительной информации, например « условных комментариев ». Такие «горячие комментарии» могут быть единственным практическим решением, обеспечивающим обратную совместимость, но многие считают их ляпом . [20]
Бывают случаи, когда обычные символы комментариев используются для создания специальной директивы для редактора или интерпретатора.
Два примера такого указания переводчику:
#!– используется в первой строке сценария, чтобы указать на используемый интерпретатор.Приведенный ниже сценарий для Unix-подобной системы демонстрирует оба этих варианта использования:
#!/usr/bin/env python3 # -*- кодировка: UTF-8 --*- print ( «Тестирование» )Несколько похоже на использование комментариев в C для сообщения компилятору о том, что «провал» по умолчанию в операторе case был сделан намеренно:
переключатель ( команда ) { случай CMD_SHOW_HELP_AND_EXIT : do_show_help (); /* Провал */ случай CMD_EXIT : сделать_выход (); перерыв ; случай CMD_OTHER : делать_другое (); перерыв ; /* ... и т. д. ... */ }Вставка такого /* Fall thru */комментария для читателей уже была обычным явлением, но в 2017 году компилятор gcc начал искать их (или другие признаки преднамеренного намерения) и, если не обнаруживал, выдавать: «Предупреждение: этот оператор может провалиться». [23]
Многие редакторы и IDE читают специально отформатированные комментарии. Например, функция Vim «modeline» ; что изменит обработку вкладок при редактировании источника с этим комментарием, включенным в верхнюю часть файла:
# vim: tabstop=8expandtab 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]
/* Это стиль, рекомендованный Голубом для C и C++. * Это продемонстрировано в разделе «Достаточно веревки», правило 29. */ /* Это еще один способ сделать это, также в C. ** Это проще сделать в редакторах, которые не делают автоматически отступ второй ** до последних строк комментария на один пробел от первого. ** Оно также используется в книге Голуба, в правиле 31. */Использование /* и */ в качестве разделителей комментариев к блокам было унаследовано от PL/I в язык программирования B, непосредственный предшественник языка программирования C. [37]
В строковых комментариях обычно используется произвольный разделитель или последовательность токенов для обозначения начала комментария и символ новой строки для обозначения конца комментария.
В этом примере весь текст от символов ASCII // до конца строки игнорируется.
// ------------------------- // Это тело комментария. // -------------------------Часто такой комментарий должен начинаться с крайнего левого угла и занимать всю строку. Однако во многих языках также можно поместить комментарий в командной строке , чтобы добавить к нему комментарий – как в этом примере Perl:
напечатайте $s . "\п" ; # Добавляем символ новой строки после печати Если язык допускает как строчные, так и блочные комментарии, команды программистов могут принять решение об использовании их по-разному: например, строчные комментарии только для второстепенных комментариев, а блочные комментарии — для описания абстракций более высокого уровня.
Программисты могут использовать неофициальные теги в комментариях, чтобы помочь индексировать распространенные проблемы. Затем их можно будет найти с помощью обычных инструментов программирования, таких как утилита grep Unix , или даже с помощью выделения синтаксиса в текстовых редакторах . Иногда их называют «кодовыми тегами» [38] [39] или «токенами», и инструменты разработки могут даже помочь вам составить их список. [40]
Такие теги сильно различаются, но могут включать в себя:
Типографские соглашения для указания комментариев сильно различаются. Более того, отдельные языки программирования иногда предоставляют уникальные варианты.
Язык программирования Ada использует '--' для обозначения комментария до конца строки.
Например:
-- задача авиадиспетчера принимает запросы на взлет и посадку типа задачи Контроллер ( My_Runway : Runway_Access ) -- записи задачи для синхронной передачи сообщений запись Request_Takeoff ( ID : in Airplane_ID ; Takeoff : out Runway_Access ); запись Request_Approach ( ID : в Airplane_ID ; Approach : out Runway_Access ); конец контроллера ; APL использует ⍝для обозначения комментария до конца строки.
Например:
⍝ Теперь складываем числа: c ← a + b ⍝ сложение В диалектах, которые имеют примитивы ⊣(«левый») и ⊢(«правый»), комментарии часто могут быть внутри или отдельными операторами в виде игнорируемых строк:
d ← 2 × c ⊣ 'где' ⊢ c ← a + 'граница' ⊢ b В этом разделе кода AppleScript показаны два стиля комментариев, используемые на этом языке.
(* Эта программа отображает приветствие. *) при приветствии ( myGreeting ) отображается диалоговое окно myGreeting & «world!» окончание приветствия-- Показать приветствие ( " Привет" ).В этом классическом раннем фрагменте кода 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:
Открытый класс Form1 Частный Sub Button1_Click ( отправитель как объект , e как EventArgs ) Обрабатывает кнопку Button1 . Нажмите кнопку «Следующий код выполняется, когда пользователь » нажимает кнопку в окне программы. rem комментарии все еще существуют. Окно сообщения . Show ( "Hello, World" ) 'Показать всплывающее окно с приветствием End Sub End Class Этот фрагмент кода C демонстрирует использование комментария пролога или «блочного комментария» для описания цели условного оператора . В комментарии объясняются ключевые термины и понятия, а также имеется короткая подпись программиста, автора кода.
/* * Проверьте, не превышен ли максимальный лимит процессов, но обязательно * исключите root. Это необходимо для того, чтобы логин и * друзья могли установить ограничение количества процессов для каждого пользователя на нечто меньшее *, чем количество запущенных корневых процессов. -- Rik */ if ( atomic_read ( & p -> user -> processes ) >= p -> rlim [ RLIMIT_NPROC ]. rlim_cur && ! способный ( CAP_SYS_ADMIN ) && ! способный ( CAP_SYS_RESOURCE )) goto bad_fork_free ; Начиная с C99, также стало возможным использовать синтаксис // из C++, обозначающий однострочный комментарий.
Наличие комментариев к блокам позволяет визуально отмечать структурные прорывы, т.е. допустимые нарушения правила структурного программирования «один вход/один выход» , как в следующем примере:
static Edge Edge_any ( Node n , Node m ) { // Возвращает, находится ли какое-либо ребро между узлами $n и $m. Край е ; for ( e = n -> ребра ; e ; e = e -> next ) { if ( e -> dst == m ) { /*********/ return e ; } } for ( e = m -> ребра ; e ; e = e -> next ) { if ( e -> dst == n ) { /*****/ break ; } } вернуть е ; } Во многих языках, где нет блочного комментария, например awk , вместо него можно использовать последовательности разделителей операторов ;. Но это невозможно в языках, использующих отступы как жесткое указание предполагаемой структуры блоков, таких как Python .
Восклицательный знак ( ! ) может использоваться для обозначения комментариев в режиме конфигурации маршрутизатора Cisco, однако такие комментарии не сохраняются в энергонезависимой памяти (которая содержит конфигурацию запуска) и не отображаются командой «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> Привет, мир < 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.
Этот фрагмент кода Фортрана демонстрирует, как в этом языке используются комментарии, причем сами комментарии описывают основные правила форматирования.
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! * Все символы после восклицательного знака считаются комментариями * !* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * program comment_test print ' (A)' , 'Hello world' ! В Фортране 90 появилась возможность встроенных комментариев. завершить программу Комментарии к строкам в Haskell начинаются с «--» (два дефиса) до конца строки, а многострочные комментарии начинаются с «{-» и заканчиваются «-}».
{- это комментарий к нескольким строкам -} -- и это комментарий к одной строке putStrLn "Wikipedia" -- это другой комментарий Haskell также предоставляет грамотный метод программирования комментариев, известный как «птичий стиль». [43] При этом все строки, начинающиеся с >, интерпретируются как код, все остальное считается комментарием. Еще одним требованием является то, что вы всегда должны оставлять пустую строку до и после блока кода:
В стиле Bird перед кодом необходимо оставить пробел.> факт :: Целое -> Целое > факт 0 = 1 > факт ( n + 1 ) = ( n + 1 ) * факт n И после кода тоже нужно оставить пустую строку.Грамотное программирование также можно выполнять на Haskell, используя LaTeX . Вместо стиля Ричарда Берда можно использовать среду кода: в стиле LaTeX это эквивалентно приведенному выше примеру: среда кода может быть определена в преамбуле LaTeX. Вот простое определение:
\usepackage { дословно } \newenvironment { code }{ \verbatim }{ \endverbatim }позже
% исходный файл LaTeX
\ verb |fact n| вызов функции вычисляет $ n ! $ if $ n \ge 0 $ , вот определение: \\ \begin { code } fact :: Integer -> Integer fact 0 = 1 fact ( n + 1 ) = ( n + 1 ) * fact n \ end { код }
Здесь больше объяснений с использованием разметки \LaTeX {}. Этот фрагмент кода Java показывает комментарий к блоку, используемый для описания setToolTipTextметода. Форматирование соответствует стандартам Javadoc Sun Microsystems . Комментарий предназначен для чтения процессором Javadoc.
/** * Это блочный комментарий в Java. * Метод setToolTipText регистрирует текст, отображаемый во всплывающей подсказке. * Текст отображается, когда курсор задерживается на компоненте. * * @param text Строка, которая будет отображаться. Если 'text' имеет значение null, * всплывающая подсказка для этого компонента отключена. */ public void setToolTipText ( String text ) { // Это встроенный комментарий в Java. ЗАДАЧА: Напишите код для этого метода. } JavaScript использует // для начала комментариев и /* */ для многострочных комментариев.
// Однострочный комментарий JavaScript var iNum = 100 ; вар 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 ./ ( факториал ( n )) % Складываем, чтобы получить приближение Тейлора, приблизительно = сумма ( seq ) Ним использует символ «#» для встроенных комментариев. Многострочные комментарии к блоку открываются с помощью '#[' и закрываются с помощью ']#'. Многострочные комментарии к блокам могут быть вложенными.
В Nim также есть комментарии к документации, в которых используются смешанные разметки Markdown и ReStructuredText . Во встроенных комментариях к документации используется символ «##», а комментарии к многострочным блокам документации открываются с помощью «##[» и закрываются с помощью «]##». Компилятор может генерировать документацию HTML , LaTeX и JSON на основе комментариев к документации. Комментарии к документации являются частью абстрактного синтаксического дерева и могут быть извлечены с помощью макросов. [45]
## Документация модуля *ReSTructuredText* и **MarkDown** # Это комментарий, но не комментарий к документации.type Kitten = object ## Документация типа age : int ## Документация поля proc purr ( self : Kitten ) = ## Документация функции echo "Purr Purr" # Это комментарий, но не комментарий документации. # Это комментарий, но не комментарий к документации.OCaml использует вложенные комментарии, что полезно при комментировании блока кода.
codeLine (* уровень комментария 1(*уровень комментария 2*)*)В Pascal и Delphi комментарии разделяются символом '{ ... }'. Строки комментариев также могут начинаться с '\\' . В качестве альтернативы для компьютеров, которые не поддерживают эти символы, допускается использование символов «(* ... *)». [46]
В более современном семействе языков Никлауса Вирта (включая Modula-2 и Oberon ) комментарии разделяются символом «(* ... *)». [47] [48]
Например:
(* тестовые диагонали *) columnsDifference := testColumn - columns ; if ( row + columnsDifference = testRow ) или ....... Комментарии могут быть вложенными. // может быть включено в {}, а {} может быть включено в (**).
Комментарии к строкам в Perl и многих других языках сценариев начинаются с символа решетки (#).
# Простой пример # my $s = "Wikipedia" ; # Устанавливает для переменной s значение «Википедия». напечатайте $s . "\п" ; # Добавляем символ новой строки после печати Вместо обычной конструкции комментирования блоков Perl использует Plain Old Documentation , язык разметки для грамотного программирования , например [49] : [50]
=item Pod::List-E<gt>new()Создайте новый объект списка. Свойства могут быть указаны через хэш- ссылку следующим образом: мой $list = Pod::List->new({ -start => $., -indent => 4 });Подробности смотрите в отдельных методах/свойствах.= вырезатьсуб новый { мой $this = сдвиг ; мой $класс = ссылка ( $this ) || $ это ; мои %params = @_ ; мой $self = { %params }; благослови $self , $class ; $self -> инициализировать (); вернуть $self ; } R поддерживает только встроенные комментарии, начинающиеся с символа решетки (#).
# Это комментарий print ( «Это не комментарий» ) # Это другой комментарий Raku (ранее называвшийся Perl 6) использует те же строчные комментарии и комментарии документации POD, что и обычный Perl (см. раздел Perl выше), но добавляет настраиваемый тип блочного комментария: «многострочные/встроенные комментарии». [51]
Они начинаются с символа решетки, за которым следует обратный апостроф, а затем какой-либо открывающий символ скобки и заканчиваются соответствующим символом закрывающей скобки. [51] Контент может не только занимать несколько строк, но также может быть встроен в строку.
#`{{ "закомментировать" эту версию toggle-case(Str:D $s)Переключает регистр каждого символа в строке: my Str $toggled-string = toggle-case("МЕНЯ ЗОВУТ МАЙКЛ!");}}sub toggle-case ( Str:D $s ) #`( эта версия скобок сейчас используется ) { ...}Комментарии в PHP могут быть либо в стиле C++ (как встроенными, так и блочными), либо использовать хеши. PHPDoc — это стиль, адаптированный из Javadoc, который является общим стандартом документирования кода PHP.
Начиная с PHP 8, знак # может означать комментарий только в том случае, если за ним сразу не следует '['. В противном случае это будет означать атрибут функции, который действует до ']':
/** * Этот класс содержит образец документации. * * @author Неизвестно */ #[ Attribute ] class MyAttribute { const VALUE = 'value' ; // Это встроенный комментарий. Он начинается с '//', как в C++. личное $значение ; # Это встроенный комментарий в стиле Unix, который начинается с '#'. общественная функция __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 . имя = 'Смит' ; -- Примечание: нам нужен только «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]
Тройные кавычки рассматриваются как обычные строки, за исключением того, что они могут занимать несколько строк.
Под обычными строками я подразумеваю, что если они не присвоены переменной, они будут немедленно удалены сборщиком мусора, как только этот код будет выполнен.
следовательно, не игнорируются интерпретатором так же, как #комментарий.