Комментарий (компьютерное программирование)
В компьютерном программировании комментарий — это понятное программисту объяснение или аннотация в исходном коде компьютерной программы . Они добавляются с целью облегчить понимание исходного кода людьми и обычно игнорируются компиляторами и интерпретаторами . [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 ]);
}
Если оставить комментарий такого типа, это упрощает процесс проверки, позволяя напрямую сравнивать код с намеченными результатами. Распространенной логической ошибкой является то, что простой для понимания код делает то, что должен .
Описание кода [ править ]
Комментарии могут использоваться для обобщения кода или для объяснения намерений программиста. Согласно этой школе мысли, пересказ кода на простом английском языке считается излишним; необходимость переосмысления кода может быть признаком того, что он слишком сложен и его следует переписать, или что имя выбрано неправильно.
- «Не документируйте плохой код – перепишите его». [9]
- «Хорошие комментарии не повторяют код и не объясняют его. Они проясняют его предназначение. Комментарии должны объяснять на более высоком уровне абстракции, чем код, то, что вы пытаетесь сделать». [10]
Комментарии также могут использоваться для объяснения того, почему блок кода не соответствует соглашениям или лучшим практикам. Это особенно верно для проектов, требующих очень мало времени на разработку или исправление ошибок. Например:
' Вторая переменная 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 « шебанг » –
#!– используется в первой строке сценария для указания используемого интерпретатора. - «Волшебные комментарии», определяющие кодировку, которую использует исходный файл, [21] например PEP 263 Python. [22]
Приведенный ниже сценарий для Unix-подобной системы демонстрирует оба этих варианта использования:
#!/usr/bin/env python3
# -*- кодировка: UTF-8 --*-
print ( «Тестирование» )
Несколько похоже на использование комментариев в C для сообщения компилятору о том, что «провал» по умолчанию в операторе case был сделан намеренно:
переключатель ( команда ) {
case CMD_SHOW_HELP_AND_EXIT :
do_show_help ();
/* Провал */
case CMD_EXIT :
do_exit ();
перерыв ;
случай CMD_OTHER :
do_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 . "\п" ; # Добавляем символ новой строки после печати
Если язык допускает как строчные, так и блочные комментарии, группы программистов могут принять решение об использовании их по-разному: например, строчные комментарии только для второстепенных комментариев, а блочные комментарии — для описания абстракций более высокого уровня.
Теги [ править ]
Программисты могут использовать неофициальные теги в комментариях, чтобы помочь индексировать распространенные проблемы. Затем их можно будет найти с помощью обычных инструментов программирования, таких как Unix утилита grep , или даже с помощью выделения синтаксиса в текстовых редакторах . Их иногда называют «кодовыми тегами». [38] [39] или «токены», а инструменты разработки могут даже помочь вам перечислить их все. [40]
Такие теги сильно различаются, но могут включать в себя:
- BUG, DEBUG — известная ошибка , которую следует исправить.
- FIXME — надо исправить.
- HACK, BODGE, KLUDGE — обходной путь.
- TODO — что-то, что нужно сделать.
- ПРИМЕЧАНИЕ — используется для выделения особо заметных ошибок .
- UNDONE — разворот или «откат» предыдущего кода.
- XXX — предупреждать других программистов о проблемном или вводящем в заблуждение коде.
Примеры [ править ]
Сравнение [ править ]
Типографские соглашения для указания комментариев сильно различаются. Более того, отдельные языки программирования иногда предоставляют уникальные варианты.
Есть [ править ]
Язык программирования 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 [ править ]
В этом разделе кода 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 IOS и IOS-XE [ править ]
Восклицательный знак ( ! ) может использоваться для обозначения комментариев в режиме конфигурации маршрутизатора Cisco, однако такие комментарии не сохраняются в энергонезависимой памяти (которая содержит конфигурацию запуска) и не отображаются командой «show run». . [41] [42]
Можно вставить удобочитаемый контент, который на самом деле является частью конфигурации и может быть сохранен в NVRAM стартовой конфигурации с помощью:
- Команда «описание», используемая для добавления описания в конфигурацию интерфейса или соседа . BGP
- Параметр «имя», чтобы добавить примечание к статическому маршруту.
- Команда «замечание» в списках доступа
! Вставьте текст ниже, чтобы перенаправить трафик вручную
конфигурация т
интервал 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, которые начинаются с '/+' и заканчиваются '+/'.
// Это однострочный комментарий.
/* Это многострочный комментарий.
*/
/+ Это
/+ вложенный +/
комментарий +/
Фортран IV [ править ]
Этот фрагмент кода Fortran IV демонстрирует, как используются комментарии в этом языке, который очень ориентирован на столбцы. Буква «C» в столбце 1 означает, что вся строка будет рассматриваться как комментарий.
C
C Строки, начинающиеся с «C» (в первом столбце или столбце «комментариев»), являются комментариями
C
WRITE ( 6 , 610 )
610 FORMAT ( 12 H HELLO WORLD )
END
Обратите внимание, что столбцы строки в противном случае обрабатываются как четыре поля: с 1 по 5 — это поле метки, 6 означает, что строка воспринимается как продолжение предыдущего оператора; а декларации и заявления идут с 7 по 72.
Фортран 90 [ править ]
Этот фрагмент кода Фортрана демонстрирует, как в этом языке используются комментарии, причем сами комментарии описывают основные правила форматирования.
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * !
* Все символы после восклицательного знака считаются комментариями *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
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
| \глагол факт 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метод. Форматирование соответствует Sun Microsystems стандартам Javadoc . Комментарий предназначен для чтения процессором Javadoc.
/**
* Это блочный комментарий в Java.
* Метод setToolTipText регистрирует текст, отображаемый во всплывающей подсказке.
* Текст отображается, когда курсор задерживается на компоненте.
*
* @param text Строка, которая будет отображаться. Если 'text' имеет значение null,
* всплывающая подсказка для этого компонента отключена.
*/
public void setToolTipText ( String text ) {
// Это встроенный комментарий в Java. ЗАДАЧА: Напишите код для этого метода.
}
JavaScript [ править ]
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 [ edit ]
Ним использует символ «#» для встроенных комментариев. Многострочные комментарии к блоку открываются с помощью '#[' и закрываются с помощью ']#'. Многострочные комментарии к блокам могут быть вложенными.
В Nim также есть комментарии к документации, в которых используются смешанные разметки Markdown и ReStructuredText . Во встроенных комментариях к документации используется символ «##», а комментарии к многострочным блокам документации открываются с помощью «##[» и закрываются с помощью «]##». Компилятор может генерировать документацию HTML , LaTeX и JSON на основе комментариев к документации. Комментарии к документации являются частью абстрактного синтаксического дерева и могут быть извлечены с помощью макросов. [45]
## Документация модуля *ReSTructuredText* и **MarkDown**
# Это комментарий, но не комментарий к документации.
type Kitten = object ## Документация типа
age : int ## Документация поля
proc purr ( self : Kitten ) =
## Документация функции
echo "Purr Purr" # Это комментарий, но не комментарий документации.
# Это комментарий, но не комментарий к документации.
OCaml [ править ]
OCaml использует вложенные комментарии, что полезно при комментировании блока кода.
codeLine (* уровень комментария 1(*уровень комментария 2*)*)
Паскаль, Дельфи [ править ]
В 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()
Создайте новый объект списка. Свойства могут быть указаны через хэш-
ссылку следующим образом:
my $list = Pod::List->new({ -start => $., -indent => 4 });
Подробности смотрите в отдельных методах/свойствах.
=cut
sub new {
my $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("mY NAME IS MIHAEL!");
}}
sub toggle-case ( Str:D $s ) #`( эта версия скобок сейчас используется ) {
...
}
PHP [ править ]
Комментарии в PHP могут быть либо в стиле C++ (как встроенными, так и блочными), либо использовать хеши. PHPDoc — это стиль, адаптированный из Javadoc, который является общим стандартом документирования кода PHP.
Начиная с PHP 8, знак # может означать комментарий только в том случае, если за ним сразу не следует '['. В противном случае это будет означать атрибут функции, который действует до ']':
/**
* Этот класс содержит образец документации.
*
* @author Неизвестно
*/
#[ Attribute ]
class MyAttribute {
const VALUE = 'value' ;
// Это встроенный комментарий. Он начинается с '//', как в C++.
личное $значение ;
# Это встроенный комментарий в стиле Unix, который начинается с '#'.
общественная функция __construct ( $value = null ) {
$this -> value = $value ;
}
/*
Это многострочный комментарий.
Эти комментарии не могут быть вложенными.
*/
}
PowerShell [ править ]
Комментарии в Windows PowerShell
# Однострочный комментарий
Write-Host "Hello, World!"
<#Многострочный
комментарий
#>
Write-Host «Прощай, мир!»
Питон [ править ]
Встроенные комментарии в Python используют символ решетки (#), как в двух примерах этого кода:
«Hello World» на экран
# Эта программа выводит ( «Hello World!» ) # Обратите внимание на новый синтаксис
Блочные комментарии, определенные в этой статье, технически не существуют в Python. [52] Можно использовать простой строковый литерал, представленный строкой в тройных кавычках: [53] но не игнорируется интерпретатором так же, как комментарий «#». [52] В приведенных ниже примерах строки в тройных двойных кавычках действуют как комментарии, но также рассматриваются как строки документации :
"""
Если это файл mymodule.py, то эта строка, будучи
первым оператором в файле, станет
строкой документации модуля "mymodule" при импорте файла.
"""
class MyClass :
"""Строка документации класса" ""
def my_method ( self ):
"""Строка документации метода"""
def my_function ():
"""Строка документации функции"""
Руби [ править ]
Встроенные комментарии в Ruby начинаются с символа #.
Чтобы создать многострочный комментарий, необходимо поместить «=begin» в начале строки, а затем все, что начинается с «=end», игнорируется. Включение пробела после знака равенства в этом случае приводит к синтаксической ошибке.
puts "Это не комментарий"
# this is a comment
puts "Это не комментарий"
=begin
все, что происходит в этих строках,
предназначено только для читателей
=end
puts "Это не комментарий"
SQL [ править ]
Стандартные комментарии в 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) [ править ]
Комментарии в XML (или HTML) вводятся с помощью
< !--
и может распространяться на несколько строк до терминатора,
-->
Например,
<!-- здесь выберите контекст -->
<param name= "context" value= "public" />
Для совместимости с SGML внутри комментариев не допускается строка «--» (двойной дефис).
Проблемы безопасности [ править ]
На интерпретируемых языках комментарии доступны для просмотра конечному пользователю программы. В некоторых случаях, например, в «закомментированных» разделах кода, это может представлять собой уязвимость безопасности . [59]
См. также [ править ]
- Docstring — комментарий особого типа, который анализируется и сохраняется на протяжении всего времени выполнения программы.
- Шебанг , использование #! как директива интерпретатора в сценариях Unix-подобных систем
- HTML-тег комментария
- Грамотное программирование , альтернативная парадигма документации.
- Синтаксис комментариев на различных языках программирования
- КОММЕНТАРИЙ (директива CONFIG.SYS)
- REM (директива CONFIG.SYS)
Примечания и ссылки [ править ]
- ^ Исходный код можно разделить на программный код (который состоит из машинно-переводимых инструкций); и комментарии (которые включают удобочитаемые примечания и другие виды аннотаций для поддержки программного кода). Пенни Грабб, Армстронг Таканг (2003). Обслуживание программного обеспечения: концепции и практика . Всемирная научная. стр. 7, начните со 120–121. ISBN 978-981-238-426-3 .
- ^ Для целей этой статьи комментарии языка программирования рассматриваются как неотличимые от комментариев, которые появляются в языках разметки , файлах конфигурации и других подобных контекстах. Более того, язык разметки часто тесно интегрирован с кодом языка программирования, особенно в контексте генерации кода . См., например, Гангули, Мадхушри (2002). Использование Jsp . Нью-Йорк: Уайли. ISBN 978-0-471-21974-3 . , Хьюитт, Эбен (2003). Java для разработчиков Coldfusion . Река Аппер-Седл: Образование Пирсона. ISBN 978-0-13-046180-3 .
- ^ Диксит, Дж. Б. (2003). Основы компьютера и программирование на C. Публикации Лакшми. ISBN 978-81-7008-882-0 .
- ^ Хайэм, Десмонд (2005). Руководство по МАТЛАБ . СИАМ. ISBN 978-0-89871-578-1 .
- ^ Вермюлен, Эл (2000). Элементы стиля Java . Издательство Кембриджского университета. ISBN 978-0-521-77768-1 .
- ^ Перейти обратно: а б с «Использование правильного комментария в Java» . 04.03.2000 . Проверено 24 июля 2007 г.
- ^ WR, Дитрих (2003). Прикладное распознавание образов: алгоритмы и реализация на C++ . Спрингер. ISBN 978-3-528-35558-6 . предлагает точки зрения на правильное использование комментариев в исходном коде. п. 66.
- ^ Перейти обратно: а б Киз, Джессика (2003). Справочник по программной инженерии . ЦРК Пресс. ISBN 978-0-8493-1479-7 . обсуждаются комментарии и «Наука о документации» с. 256.
- ^ Перейти обратно: а б с Элементы стиля программирования , Керниган и Плаугер
- ^ Перейти обратно: а б Код завершен , МакКоннелл
- ^ Спинеллис, Диомидис (2003). Чтение кода: Перспектива открытого исходного кода . Аддисон-Уэсли. ISBN 978-0-201-79940-8 .
- ^ «CodePlotter 1.6 — добавляйте и редактируйте диаграммы в своем коде с помощью этого инструмента, похожего на Visio» . Архивировано из оригинала 14 июля 2007 г. Проверено 24 июля 2007 г.
- ^ Перейти обратно: а б Нидерст, Дженнифер (2006). Коротко о веб-дизайне: краткий справочник по настольному компьютеру . О'Рейли. ISBN 978-0-596-00987-8 . Иногда разница между «комментарием» и другими элементами синтаксиса языка программирования или разметки влечет за собой тонкие нюансы. Нидерст указывает на одну из таких ситуаций, заявляя: «К сожалению, программное обеспечение XML воспринимает комментарии как неважную информацию и может просто удалить комментарии из документа перед его обработкой. Чтобы избежать этой проблемы, используйте вместо этого раздел XML CDATA».
- ^ См., например, Винн-Пауэлл, Род (2008). Mac OS X для фотографов: оптимизированный рабочий процесс обработки изображений для пользователей Mac . Оксфорд: Focal Press. п. 243. ИСБН 978-0-240-52027-8 .
- ^ Лэмб, Линда (1998). Изучение редактора VI . Севастополь: О'Рейли и партнеры. ISBN 978-1-56592-426-0 . описывает использование синтаксиса modeline в файлах конфигурации Vim.
- ^ См., например, Берлин, Дэниел (2006). Практическая подрывная деятельность, второе издание . Беркли: APress. п. 168. ИСБН 978-1-59059-753-8 .
- ^ Эмблер, Скотт (2004). Учебник по объектам: гибкая разработка на основе моделей с использованием UML 2.0 . Издательство Кембриджского университета. ISBN 978-1-397-80521-8 .
- ^ Определение функции с помощью строки документации в Clojure
- ^ Стены. С#2005 . стр. 56.
- ^ c2: Горячие комментарии
- ^ «Кодировка класса» . Рубин . Ruby-lang.org . Проверено 5 декабря 2018 г.
- ^ «PEP 263 – Определение кодировки исходного кода Python» . Python.org . Проверено 5 декабря 2018 г.
- ^ Полачек, Марек (10 марта 2017 г.). «-Wimplicit-fallthrough в GCC 7» . Разработчик Red Hat . Красная Шапка . Проверено 10 февраля 2019 г.
- ^ Лиза Эдичико (27 марта 2014 г.). «Программисты Microsoft спрятали кучу ненормативной лексики в раннем программном коде» . Бизнес-инсайдер Австралии . Архивировано из оригинала 29 декабря 2016 года.
- ^ (см., например, « Счетчик ругательств в Linux »).
- ^ Гудлифф, Пит (2006). Код Крафт . Сан-Франциско: Пресса без крахмала. ISBN 978-1-59327-119-0 .
- ^ Smith, T. (1991). Intermediate Programming Principles and Techniques Using Pascal. Belmont: West Pub. Co. ISBN 978-0-314-66314-6.
- ^ См., например, Колецке, Питер (2000). Расширенные формы и отчеты для разработчиков Oracle . Беркли: Осборн/МакГроу-Хилл. ISBN 978-0-07-212048-6 . страница 65.
- ^ «Худшая практика – плохие комментарии» . Проверено 24 июля 2007 г.
- ^ Морелли, Ральф (2006). Java, Java, Java: объектно-ориентированное решение задач . Колледж Прентис Холл. ISBN 978-0-13-147434-5 .
- ^ Перейти обратно: а б «Как писать комментарии к документу для инструмента Javadoc» . Проверено 24 июля 2007 г. Рекомендации Javadoc указывают, что комментарии имеют решающее значение для платформы. Кроме того, соответствующий уровень детализации довольно четко определен: «Мы тратим время и усилия, сосредоточившись на определении граничных условий, диапазонов аргументов и крайних случаев, а не на определении общих терминов программирования, написании концептуальных обзоров и включении примеров для разработчиков».
- ^ Юрдон, Эдвард (2007). Методы структуры и дизайна программ . Университет Мичигана. 013901702X. Несуществующие комментарии могут затруднить понимание кода, но комментарии могут быть вредными, если они устаревшие, избыточные, неправильные или иным образом затрудняют понимание предполагаемой цели исходного кода.
- ^ Дьюхерст, Стивен С. (2002). Советы по C++: как избежать распространенных проблем при кодировании и проектировании . Аддисон-Уэсли Профессионал. ISBN 978-0-321-12518-7 .
- ^ «Стиль кодирования» . Архивировано из оригинала 8 августа 2007 г. Проверено 24 июля 2007 г.
- ^ «Аллен Голуб» . Архивировано из оригинала 20 июля 2007 г. Проверено 24 июля 2007 г.
- ^ Аллен Голуб, Достаточно веревки, чтобы выстрелить себе в ногу , ISBN 0-07-029689-8 , 1995, МакГроу-Хилл
- ^ Кен Томпсон. «Ссылка пользователей на B» . Проверено 21 июля 2017 г.
- ^ "PEP 0350 - Кодовые теги" , Python Software Foundation
- ^ «Никогда ничего не забывайте до, после и во время кодирования» , использование комментариев «codetag» в качестве продуктивных остатков
- ^ «Использование списка задач» , msdn.microsoft.com.
- ^ «Оставить комментарий в текущей конфигурации» . Cisco Learning Network (дискуссионный форум) .
- ^ «Руководство по настройке управления файлами конфигурации, Cisco IOS XE Release 3S (серия ASR 900)» .
- ^ «Грамотное программирование» . Haskell.org .
- ^ «Программирование на Lua 1.3» . www.Lua.org . Проверено 8 ноября 2017 г.
- ^ macros.extractDocCommentsAndRunnables
- ^ Кэтлин Дженсен, Никлаус Вирт (1985). Руководство пользователя и отчет Pascal . Издательство Спрингер. ISBN 0-387-96048-1 .
- ^ Никлаус Вирт (1983). Программирование в Модуле-2 . Издательство Спрингер. ISBN 0-387-15078-1 .
- ^ * Мартин Райзер, Никлаус Вирт (1992). Программирование в Обероне . Аддисон-Уэсли. ISBN 0-201-56543-9 .
- ^ «perlpod – старый добрый формат документации» . Проверено 12 сентября 2011 г.
- ^ «Pod::ParseUtils — помощники для анализа и преобразования POD» . Проверено 12 сентября 2011 г.
- ^ Перейти обратно: а б «Документация Perl 6 — Синтаксис (комментарии)» . Проверено 6 апреля 2017 г.
- ^ Перейти обратно: а б «Базовый синтаксис Python 3» . Архивировано из оригинала 19 августа 2021 года . Проверено 25 февраля 2019 г.
Тройные кавычки рассматриваются как обычные строки, за исключением того, что они могут занимать несколько строк. Под обычными строками я подразумеваю, что если они не присвоены переменной, они будут немедленно удалены сборщиком мусора, как только этот код будет выполнен. следовательно, не игнорируются интерпретатором так же, как #a comment.
- ^ «Совет по Python: вы можете использовать многострочные строки в качестве многострочных комментариев» , 11 сентября 2011 г., Гвидо ван Россум
- ^ Талмейдж, Рональд Р. (1999). Microsoft SQL-сервер 7 . Издательство Прима. ISBN 978-0-7615-1389-6 .
- ^ «Справочное руководство MySQL 8.0» . Корпорация Оракл . Проверено 2 января 2020 г.
- ^ «SQL в понимании SQLite» . Консорциум SQLite . Проверено 2 января 2020 г.
- ^ «Документация PostgreSQL 10.11» . Группа глобального развития PostgreSQL . Проверено 2 января 2020 г.
- ^ «Справочник по SQL базы данных Oracle®» . Корпорация Оракл . Проверено 2 января 2020 г.
- ^ Андресс, Мэнди (2003). Выживание в безопасности: как интегрировать людей, процессы и технологии . ЦРК Пресс. ISBN 978-0-8493-2042-2 .
Дальнейшее чтение [ править ]
- Мовшовиц-Аттиас, Дана и Коэн, Уильям В. (2013) Модели естественного языка для прогнозирования комментариев к программированию . В Ассоциации компьютерной лингвистики (ACL), 2013 г.