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

В программировании на компьютере комментарий — это текст, встроенный в исходный код , который игнорируется транслятором ( компилятором или интерпретатором ). Как правило, комментарий — это аннотация , призванная сделать код более понятным для программиста — часто объясняющая аспект, который неочевиден в программном (некомментарном) коде. ^[1] В этой статье комментарий относится к той же концепции в языке программирования , языке разметки , файле конфигурации и любом подобном контексте. ^[2] Некоторые инструменты разработки , кроме транслятора исходного кода, анализируют комментарии для предоставления таких возможностей, как генерация документов API , статический анализ и интеграция с контролем версий . Синтаксис комментариев различается в зависимости от языка программирования, однако существуют повторяющиеся шаблоны в синтаксисе среди языков, а также схожие аспекты, связанные с содержимым комментариев.

Гибкость, поддерживаемая комментариями, допускает широкую степень вариативности стиля контента. Для обеспечения единообразия соглашения о стиле обычно являются частью руководства по стилю программирования . Но лучшие практики спорны и противоречивы. ^{[3] [4]}

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

Большинство языков поддерживают многострочные блочные (или потоковые) и/или однострочные комментарии. Блочный комментарий ограничивается текстом , который отмечает начало и конец текста комментария. Он может охватывать несколько строк или занимать любую часть строки. Некоторые языки позволяют рекурсивно вкладывать блочные комментарии друг в друга, но другие этого не делают. ^{[5] [6] [7]} Строчный комментарий заканчивается в конце текстовой строки. В современных языках строчный комментарий начинается с разделителя, но некоторые старые языки обозначают столбец, в котором последующий текст считается комментарием. ^[7] Многие языки поддерживают как блочные, так и строчные комментарии — используя разные разделители для каждого. Например, C , C++ и их многочисленные производные поддерживают блочные комментарии, разделенные /*и */, и строчные комментарии, разделенные //. Другие языки поддерживают только один тип комментариев. ^[7]

Комментарии также можно классифицировать как прологовые или встроенные в зависимости от их положения и содержания относительно программного кода. Прологовый комментарий — это комментарий (или группа связанных комментариев), расположенный в верхней части связанной темы программирования, например, перед объявлением символа или в верхней части файла. Встроенный комментарий — это комментарий, расположенный на той же строке и справа от программного кода, на который он ссылается. ^[8] Как прологовые, так и встроенные комментарии могут быть представлены как строчные или блочные комментарии. Например:

/* * комментарий блока пролога; если это о foo() */ bool foo () { return true ; /* комментарий встроенного блока; если это о этом return */ }     // // комментарий к строке пролога; если это примерно bar() // bool bar () { return false ; // комментарий к строке пролога; если это примерно return }     

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

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

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

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

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

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

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

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

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

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

Когда какой-либо аспект кода основан на информации во внешней ссылке, комментарии ссылаются на ссылку. Например, как URL или название книги и номер страницы.

Распространенная практика разработчиков — комментировать одну или несколько строк кода. Программист добавляет синтаксис комментариев, который преобразует программный код в комментарии, так что то, что было исполняемым кодом, больше не будет выполняться во время выполнения. Иногда этот прием используется для поиска причины ошибки. Систематически комментируя и запуская части программы, можно найти проблемный исходный код.

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

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

Некоторые инструменты программирования записывают метаданные в код в виде комментариев. ^[12] Например, инструмент контроля версий может записывать метаданные, такие как автор, дата и номер версии, в каждый файл, когда он фиксируется в репозитории. ^[13]

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

Некоторые редакторы исходного кода поддерживают настройку через метаданные в комментариях. ^[14] Одним из конкретных примеров является функция modeline в Vim , которая настраивает обработку символов табуляции. Например:

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

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

Хотя некоторые утверждают, что документация API может быть более качественной, если написана более традиционным и ручным способом, некоторые утверждают, что хранение информации о документации в комментариях кода упрощает процесс документирования, а также увеличивает вероятность того, что документация будет актуальна. ^[15] Примерами являются Javadoc , Ddoc , Doxygen , Visual Expert и PHPDoc . Формы docstring поддерживаются Python , Lisp , Elixir и Clojure . ^[16] C# , F# и Visual Basic .NET реализуют похожую функцию, называемую «XML Comments», которые считываются IntelliSense из скомпилированной сборки .NET . ^[17]

В комментарий можно включить ASCII - визуализацию искусства , например логотип , диаграмму или блок-схему . ^[18]

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

<!-- начало: 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> 

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

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

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

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

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

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

#!/usr/bin/env python3 # -*- кодировка: UTF-8 -*- печать ( "Тестирование" )

Компилятор gcc (с 2017 года) ищет комментарий в операторе switch , если case fall-thru переходит в следующий case. Если явное указание fall-thru не найдено, то компилятор выдает предупреждение о возможной проблеме кодирования. Вставка такого комментария о fall-thru является давней традицией, и компилятор кодифицировал эту практику. ^[23] Например:

переключатель ( команда ) {   случай CMD_SHOW_HELP_AND_EXIT :  do_show_help (); /* Провал */ случай CMD_EXIT :  do_exit (); перерыв ; }

Чтобы снять стресс или попытаться пошутить, программисты иногда добавляют комментарии о качестве кода, инструментах, конкурентах, работодателях, условиях труда или других, возможно, непрофессиональных темах — иногда используя ненормативную лексику . ^{[24] [25]}

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

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

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

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

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

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

String s = "Wikipedia" ; /* Присваивает значение "Wikipedia" переменной s. */    

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

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

Следующие фрагменты на языке C демонстрируют некоторое разнообразие стилей блочных комментариев:

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

/******************************\ * * * Это текст комментария. * * * \******************************/

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

Консультант по программному обеспечению и технологический комментатор Аллен Холуб ^[35] выступает за выравнивание левого края комментариев: ^[36]

 /* Это стиль, рекомендованный Голубом для C и C++.  * Он продемонстрирован в ''Enough Rope'', в правиле 29.  */

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

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

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

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

Программисты часто используют одно из выбранных слов – также известных как теги , кодовые теги ^{[37] [38]} и токены ^[39] – для категоризации информации в комментарии. Программисты могут использовать эти теги, выполняя поиск с помощью текстового редактора или grep . Некоторые редакторы выделяют текст комментария на основе тегов.

Обычно используемые теги включают в себя:

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

Например:

инт фоо() { // TODO реализовать}

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

Многие языки с фигурными скобками, такие как C, C++ и их многочисленные производные, разделяют строчный комментарий с помощью //, а блочный комментарий с помощью /*и */. Первоначально в C отсутствовал строчный комментарий, но он был добавлен в C99 . Известные языки включают: C, C++, C# , D , Java , JavaScript и Swift . Например:

/* * Проверьте, превышен ли максимальный лимит процессов, но обязательно исключите root. * Это необходимо, чтобы при входе в систему можно было установить лимит процессов для каждого пользователя * на значение ниже, чем количество запущенных процессов root. */ bool isOverMaximumProcessLimit () { // TODO implement }   

Некоторые языки, включая D и Swift, допускают вложение блоков, а другие — нет, включая C и C++.

Пример вложенных блоков в D:

// строчный комментарий /*  блочный комментарий */ /+ начало внешнего блока  /+ внутренний блок +/  конец внешнего блока +/

Пример вложенных блоков в Swift:

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

Шаблон во многих скриптовых языках заключается в том, чтобы разделять строчный комментарий с помощью #. Поддержка блочного комментария варьируется. Известные языки включают: Bash , Raku , Ruby , Perl , PowerShell , Python и R .

Пример на языке R:

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

Блочный комментарий разделяется =beginи , =endкоторые начинают строку. Например:

puts "не комментарий" # это комментарий puts "не комментарий" =begin все, что написано в этих строках, предназначено только для человеческого читателя =end puts "не комментарий"   

Вместо обычной конструкции блочного комментария Perl использует литературное программирование с использованием разметки POD (простой старой документации) . ^[40] Например: ^[41]

=item Pod::List-E<gt>new() Создать новый объект списка. Свойства могут быть указаны через ссылку на хэш, например:  my $list = Pod::List->new({ -start => $., -indent => 4 }); =cut sub new { ... }   

Raku (ранее называвшийся Perl 6) использует те же строчные комментарии и комментарии POD, что и Perl , но добавляет настраиваемый тип блочного комментария: «многострочные / встроенные комментарии». ^[42] Он начинается с #`открывающей скобки и заканчивается соответствующим закрывающей скобкой. ^[42] Например:

#`{{ "закомментировать" эту версию toggle-case(Str:D $s) Переключает регистр каждого символа в строке:  my Str $toggled-string = toggle-case("mY NAME IS mICHAEL!"); }} sub  toggle-case ( Str:D  $s ) #`( эта версия скобок используется сейчас ) { ...}

PowerShell поддерживает блочный комментарий, разделенный <#и #>. Например:

# Однострочный комментарий <# Многострочный  комментарий  #>

Хотя Python не предусматривает блочные комментарии ^[43], для этой цели часто используется голый строковый литерал , представленный строкой, заключенной в тройные кавычки. ^{[44] [43]} В приведенных ниже примерах строки, заключенные в тройные двойные кавычки, действуют как комментарии, но также рассматриваются как строки документации :

""" В верхней части файла находится строка документации модуля """класс  MyClass : """Строка документации класса"""  def  my_method ( self ): """Строка документации метода""" 

Языки разметки в целом различаются по синтаксису комментариев, но некоторые из известных форматов интернет-разметки, такие как HTML и XML, разделяют блочный комментарий с помощью <!--и -->и не поддерживают строчные комментарии. Пример в XML:

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

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

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

Относительно свободный набор языков, используемых --для однострочного комментария. Известные языки включают: Ada , Eiffel , Haskell , Lua , SQL и VHDL . Поддержка блочных комментариев варьируется. Пример на 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 ;                

В Haskell блочный комментарий разделяется {-и -}. Например:

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

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

В стиле Bird перед кодом необходимо оставить пробел.> факт :: Целое число -> Целое число > факт 0 = 1 > факт ( n + 1 ) = ( n + 1 ) * факт n             И после кода тоже нужно оставить пустую строку.

Грамотное программирование также может быть выполнено с помощью 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 {}              

Lua поддерживает блочные комментарии, разделенные символами --[[и ]]^[46]. Например:

--[[Многострочный длинный комментарий ]]

В некоторых вариантах SQL /**/поддерживается комментарий блока языка в фигурных скобках ( ). Варианты включают: Transact-SQL , MySQL , SQLite , PostgreSQL и Oracle . ^{[47] [48] [49] [50] [51]}

MySQL также поддерживает строчный комментарий, разделенный символом #.

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

⍝ Теперь складываем числа: c ← a + b ⍝ сложение 

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

d ← 2 × c ⊣ 'где' ⊢ c ← a + 'связан' ⊢ b    

AppleScript поддерживает как строчные, так и блочные комментарии. Например:

# строка комментария (в более поздних версиях) (* Эта программа отображает приветствие. *) on  greet ( myGreeting )  display dialog  myGreeting  &  " world!" end  greet-- Показать приветственное приветствие ( "Привет" )

В ранних версиях BASIC для обозначения строчного комментария использовалось REMсокращение от remark.

10 REM Эта программа BASIC демонстрирует использование операторов PRINT и GOTO. 15 REM Она заполняет экран фразой "HELLO" 20 PRINT "HELLO" 30 GOTO 20      

В более поздних вариациях, включая Quick Basic , Q Basic , Visual Basic (VB), VB.NET , VBScript , FreeBASIC и Gambas , строка комментария отделяется '(апострофом). Пример в VB.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                   

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

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

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

! Вставьте текст ниже, чтобы вручную перенаправить трафикконфигурация тцелочисленный 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закрытьВыход

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

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

Следующий фрагмент кода Fortran 90 демонстрирует более современный синтаксис строчного комментария; текст после !.

! Программа комментариев comment_test print '(A)' , 'Hello world' ! также программа комментариев end    

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

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

Nim разделяет строчный комментарий с помощью #, а блочные комментарии — с помощью #[и ]#. Блочные комментарии могут быть вложенными.

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

## Документация модуля *ReSTructuredText* и **MarkDown** # Это комментарий, но это не комментарий к документации.тип Котенок = объект ## Документация типа возраст : int ## Документация поля       proc purr ( self : Kitten ) = ## Документация функции echo "Purr Purr" # Это комментарий, но это не комментарий документации.       # Это комментарий, но не комментарий к документации.

OCaml поддерживает вложенные комментарии. Например:

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

В Pascal и Delphi блочный комментарий разделяется символами {и }, а в качестве альтернативы для компьютеров, которые не поддерживают эти символы, (*также *)поддерживаются. Строчный комментарий разделяется символами \\. ^[55] В более современном семействе языков Никлауса Вирта (включая Modula-2 и Oberon ) комментарии разделяются символами (*и *). ^{[56] [57]} Комментарии могут быть вложенными. Например:

(* проверка диагоналей *) columnDifference := testColumn - column ; if ( row + columnDifference = testRow ) или .......           

Комментарии в PHP могут быть в стиле фигурных скобок (как строка, так и блок), или строка, разделенная #l. Блоки не могут быть вложенными. Начиная с PHP 8, a #означает комментарий только в том случае, если за ним не следует непосредственно [. В противном случае он разделяет атрибут, который продолжается до следующего ]. Например:

/** * Этот класс содержит пример документации. * @author Unknown */ #[ Attribute ] class  MyAttribute  {  const  VALUE  =  'value' ;  // Комментарий в стиле C++  private  $value ;  # Комментарий в стиле скрипта  public  function  __construct ( $value  =  null )  {  $this -> value  =  $value ;  } }

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

• Сравнение языков программирования (синтаксис)#Комментарии

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

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