Комментарий (компьютерное программирование)
В компьютерном программировании комментарий — это понятное программисту объяснение или аннотация в исходном коде программы компьютерной . Они добавляются с целью облегчить понимание исходного кода людьми и обычно игнорируются компиляторами и интерпретаторами . [1] [2] Синтаксис комментариев в разных языках программирования значительно различается.
Комментарии иногда также обрабатываются различными способами для создания документации, внешней по отношению к самому исходному коду, с помощью генераторов документации или используются для интеграции с системами управления исходным кодом и другими видами внешних инструментов программирования .
Гибкость, обеспечиваемая комментариями, допускает широкую степень вариативности, но формальные соглашения по их использованию обычно являются частью руководств по стилю программирования .
Обзор [ править ]
Комментарии обычно форматируются либо как блочные комментарии (также называемые комментариями пролога или комментариями потока ), либо как строчные комментарии (также называемые встроенными комментариями ). [3]
Блочные комментарии ограничивают область исходного кода, которая может занимать несколько строк или часть одной строки. Этот регион указывается с начальным и конечным разделителем. Некоторые языки программирования (например, MATLAB ) позволяют рекурсивно вкладывать комментарии блоков друг в друга, но другие (например, Java ) этого не делают. [4] [5] [6]
Комментарии к строке либо начинаются с разделителя комментариев и продолжаются до конца строки, либо, в некоторых случаях, начинаются с определенного столбца (смещения строки символов) в исходном коде и продолжаются до конца строки. [6]
В некоторых языках программирования используются как блочные, так и строковые комментарии с разными разделителями комментариев. Например, в C++ есть блочные комментарии, разделенные /* и */ который может охватывать несколько строк и комментариев к строкам, разделенных //. Другие языки поддерживают только один тип комментариев. Например, комментарии Ada являются строковыми комментариями: они начинаются с -- и продолжайте до конца строки. [6]
Использует [ править ]
Вопрос о том, как лучше всего использовать комментарии, является предметом споров; разные комментаторы высказывали разные, а иногда и противоположные точки зрения. [7] [8] Есть много разных способов написания комментариев, и многие комментаторы дают противоречивые советы. [8]
Планирование и анализ [ править ]
Комментарии можно использовать как форму псевдокода , чтобы обозначить намерение перед написанием фактического кода. В этом случае следует объяснять логику кода, а не сам код.
/* loop backwards through all elements returned by the server
(they should be processed chronologically)*/
for (i = (numElementsReturned - 1); i >= 0; i--) {
/* process each element's data */
updatePattern(i, returnedElements[i]);
}
Если оставить комментарий такого типа, это упрощает процесс проверки, позволяя напрямую сравнивать код с намеченными результатами. Распространенной логической ошибкой является то, что простой для понимания код делает то, что должен .
Описание кода [ править ]
Комментарии могут использоваться для обобщения кода или для объяснения намерений программиста. Согласно этой школе мысли, пересказ кода на простом английском языке считается излишним; необходимость переосмысления кода может быть признаком того, что он слишком сложен и его следует переписать, или что имя выбрано неправильно.
- «Не документируйте плохой код – перепишите его». [9]
- «Хорошие комментарии не повторяют код и не объясняют его. Они проясняют его предназначение. Комментарии должны объяснять на более высоком уровне абстракции, чем код, то, что вы пытаетесь сделать». [10]
Комментарии также могут использоваться для объяснения того, почему блок кода не соответствует соглашениям или лучшим практикам. Это особенно верно для проектов, требующих очень мало времени на разработку или исправление ошибок. Например:
' Second variable dim because of server errors produced when reuse form data. No
' documentation available on server behavior issue, so just coding around it.
vtx = server.mappath("local settings")
Алгоритмическое описание [ править ]
Иногда исходный код содержит новое или заслуживающее внимания решение конкретной проблемы. В таких случаях комментарии могут содержать пояснение методики. Такие объяснения могут включать диаграммы и формальные математические доказательства. Это может представлять собой объяснение кода, а не разъяснение его назначения; но другие, кому поручено поддерживать базу кода, могут найти такое объяснение решающим. Это может быть особенно верно в случае узкоспециализированных проблемных областей; или редко используемые оптимизации, конструкции или вызовы функций. [11]
Например, программист может добавить комментарий, объясняющий, почему была выбрана сортировка вставками вместо быстрой сортировки , поскольку первая теоретически работает медленнее, чем вторая. Это можно было бы записать следующим образом:
list = [f (b), f (b), f (c), f (d), f (a), ...];
// Need a stable sort. Besides, the performance really does not matter.
insertion_sort (list);
Включение ресурсов [ править ]
Логотипы , диаграммы и блок-схемы, состоящие из художественных конструкций ASCII, можно вставлять в исходный код в виде комментариев. [12] Кроме того, уведомления об авторских правах могут быть встроены в исходный код в виде комментариев. Двоичные данные также могут быть закодированы в комментариях с помощью процесса, известного как кодирование двоичного текста в текст , хотя такая практика встречается редко и обычно относится к внешним файлам ресурсов.
Следующий фрагмент кода представляет собой простую диаграмму ASCII, изображающую поток процесса для сценария системного администрирования , содержащегося в файле сценария Windows, работающем под управлением узла сценариев Windows . Хотя раздел, обозначающий код, отображается как комментарий, сама диаграмма фактически отображается в разделе XML CDATA , который технически считается отличным от комментариев, но может служить аналогичным целям. [13]
<!-- begin: wsf_resource_nodes -->
<resource id="ProcessDiagram000">
<![CDATA[
HostApp (Main_process)
|
V
script.wsf (app_cmd) --> ClientApp (async_run, batch_process)
|
|
V
mru.ini (mru_history)
]]>
</resource>
Хотя эту идентичную диаграмму можно было бы легко включить в качестве комментария, пример иллюстрирует один случай, когда программист может отказаться от использования комментариев как способа включения ресурсов в исходный код. [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
# -*- coding: UTF-8 -*-
print("Testing")
Несколько похоже на использование комментариев в C для сообщения компилятору о том, что «провал» по умолчанию в операторе case был сделан намеренно:
switch (command) {
case CMD_SHOW_HELP_AND_EXIT:
do_show_help();
/* Fall thru */
case CMD_EXIT:
do_exit();
break;
case CMD_OTHER:
do_other();
break;
/* ... etc. ... */
}
Вставка такого /* Fall thru */ комментарии для читателей-людей уже были обычным явлением, но в 2017 году компилятор gcc начал искать их (или другие признаки преднамеренного намерения) и, если их не найти, выдавать: «предупреждение: это утверждение может провалиться». [23]
Многие редакторы и IDE читают специально отформатированные комментарии. Например, функция Vim «modeline» ; что изменит обработку вкладок при редактировании источника с этим комментарием, включенным в верхнюю часть файла:
# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4
Снятие стресса [ править ]
Иногда программисты добавляют комментарии, чтобы снять стресс, комментируя инструменты разработки, конкурентов, работодателей, условия работы или качество самого кода. [24] Возникновение этого явления можно легко увидеть на онлайн-ресурсах, отслеживающих ненормативную лексику в исходном коде. [25]
взгляды Нормативные
Существуют различные нормативные взгляды и устоявшиеся мнения относительно правильного использования комментариев в исходном коде. [26] [27] Некоторые из них носят неофициальный характер и основаны на личных предпочтениях, тогда как другие публикуются или распространяются в качестве официальных руководящих принципов для конкретного сообщества. [28]
Нужны комментарии [ править ]
Эксперты имеют разные точки зрения на то, уместны ли комментарии в исходном коде и если да, то когда. [9] [29] Некоторые утверждают, что исходный код должен быть написан с небольшим количеством комментариев, исходя из того, что исходный код должен быть понятным и самодокументированным . [9] Другие предлагают, чтобы код был подробно комментирован (нередко более 50% непробельных символов в исходном коде содержатся в комментариях). [30] [31]
Между этими точками зрения находится утверждение, что комментарии сами по себе не являются ни полезными, ни вредными, и важно то, что они корректны и синхронизированы с исходным кодом, и опускаются, если они излишни, чрезмерны, сложны в обслуживании или иным образом бесполезны. [32] [33]
Комментарии иногда используются для документирования контрактов при проектировании контрактного подхода к программированию.
Уровень детализации [ править ]
В зависимости от целевой аудитории кода и других соображений уровень детализации и описания могут значительно различаться.
Например, следующий комментарий Java подойдет для вводного текста, предназначенного для обучения начинающим программистам:
String s = "Wikipedia"; /* Assigns the value "Wikipedia" to the variable s. */
Однако такой уровень детализации не подходит в контексте производственного кода или других ситуаций, в которых участвуют опытные разработчики. Такие элементарные описания не соответствуют руководящему принципу: «Хорошие комментарии… проясняют намерения». [10] Кроме того, для профессиональных сред кодирования уровень детализации обычно четко определен для удовлетворения конкретных требований к производительности, определенных бизнес-операциями. [31]
Стили [ править ]
Существует множество стилистических альтернатив при рассмотрении того, как комментарии должны выглядеть в исходном коде. Для более крупных проектов, в которых участвует команда разработчиков, стили комментариев либо согласовываются до начала проекта, либо развиваются в зависимости от соглашения или необходимости по мере роста проекта. Обычно программисты предпочитают последовательные, ненавязчивые, легко модифицируемые и трудно нарушаемые стили. [34]
Заблокировать комментарий [ править ]
Следующие фрагменты кода на C демонстрируют лишь небольшой пример того, как комментарии могут различаться стилистически, но при этом передавать одну и ту же основную информацию:
/*
This is the comment body.
Variation One.
*/
/***************************\
* *
* This is the comment body. *
* Variation Two. *
* *
\***************************/
Такие факторы, как личные предпочтения, гибкость инструментов программирования и другие соображения, обычно влияют на стилистические варианты, используемые в исходном коде. Например, второй вариант может не понравиться программистам, у которых нет редакторов исходного кода , которые могут автоматизировать выравнивание и внешний вид текста в комментариях.
Консультант по программному обеспечению и технологический комментатор Аллен Голуб [35] один из экспертов выступает за выравнивание левых краев комментариев: [36]
/* This is the style recommended by Holub for C and C++.
* It is demonstrated in ''Enough Rope'', in rule 29.
*/
/* This is another way to do it, also in C.
** It is easier to do in editors that do not automatically indent the second
** through last lines of the comment one space from the first.
** It is also used in Holub's book, in rule 31.
*/
Использование /* и */ в качестве разделителей комментариев к блокам было унаследовано от PL/I в язык программирования B, непосредственный предшественник языка программирования C. [37]
Комментарии к строке [ править ]
В комментариях к строкам обычно используется произвольный разделитель или последовательность токенов для обозначения начала комментария и символ новой строки для обозначения конца комментария.
В этом примере весь текст от символов ASCII // до конца строки игнорируется.
// -------------------------
// This is the comment body.
// -------------------------
Часто такой комментарий должен начинаться с крайнего левого угла и занимать всю строку. Однако во многих языках также можно поместить комментарий в командной строке, чтобы добавить к нему комментарий – как в этом примере Perl:
print $s . "\n"; # Add a newline character after printing
Если язык допускает как строчные, так и блочные комментарии, группы программистов могут принять решение об использовании их по-разному: например, строчные комментарии только для второстепенных комментариев, а блочные комментарии — для описания абстракций более высокого уровня.
Теги [ править ]
Программисты могут использовать неофициальные теги в комментариях, чтобы помочь индексировать распространенные проблемы. Затем их можно будет найти с помощью обычных инструментов программирования, таких как Unix утилита grep , или даже с помощью выделения синтаксиса в текстовых редакторах . Их иногда называют «кодовыми тегами». [38] [39] или «токены», а инструменты разработки могут даже помочь вам перечислить их все. [40]
Такие теги сильно различаются, но могут включать в себя:
- BUG, DEBUG — известная ошибка , которую следует исправить.
- FIXME — надо исправить.
- HACK, BODGE, KLUDGE — обходной путь.
- TODO — что-то, что нужно сделать.
- ПРИМЕЧАНИЕ — используется для выделения особо заметных ошибок .
- UNDONE — разворот или «откат» предыдущего кода.
- XXX — предупреждать других программистов о проблемном или ошибочном коде.
Примеры [ править ]
Сравнение [ править ]
Типографские соглашения для указания комментариев сильно различаются. Более того, отдельные языки программирования иногда предоставляют уникальные варианты.
Есть [ править ]
Язык программирования Ada использует '--' для обозначения комментария до конца строки.
Например:
-- the air traffic controller task takes requests for takeoff and landing
task type Controller (My_Runway: Runway_Access) is
-- task entries for synchronous message passing
entry Request_Takeoff (ID: in Airplane_ID; Takeoff: out Runway_Access);
entry Request_Approach(ID: in Airplane_ID; Approach: out Runway_Access);
end Controller;
АПЛ [ править ]
APL использует ⍝ для указания комментария до конца строки.
Например:
⍝ Now add the numbers:
c←a+b ⍝ addition
В диалектах, имеющих ⊣ («левый») и ⊢ («правильные») примитивы, комментарии часто могут быть внутри или отдельными операторами в виде игнорируемых строк:
d←2×c ⊣'where'⊢ c←a+ 'bound'⊢ b
AppleScript [ править ]
В этом разделе кода AppleScript показаны два стиля комментариев, используемые на этом языке.
(*
This program displays a greeting.
*)
on greet(myGreeting)
display dialog myGreeting & " world!"
end greet
-- Show the greeting
greet("Hello")
БАЗОВЫЙ [ править ]
В этом классическом раннем фрагменте кода BASIC ключевое слово REM ( «Remark» ) используется для добавления комментариев.
10 REM This BASIC program shows the use of the PRINT and GOTO Statements.
15 REM It fills the screen with the phrase "HELLO"
20 PRINT "HELLO"
30 GOTO 20
В более поздних версиях Microsoft BASIC, включая Quick Basic , Q Basic , Visual Basic , Visual Basic .NET и VB Script ; а в потомках, таких как FreeBASIC и Gambas, любой текст в строке после символа ' (апострофа) также рассматривается как комментарий.
Пример в Visual Basic .NET:
Public Class Form1
Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
' The following code is executed when the user
' clicks the button in the program's window.
rem comments still exist.
MessageBox.Show("Hello, World") 'Show a pop-up window with a greeting
End Sub
End Class
С [ править ]
Этот фрагмент кода C демонстрирует использование комментария пролога или «блочного комментария» для описания цели условного оператора . В комментарии объясняются ключевые термины и понятия, а также имеется короткая подпись программиста, автора кода.
/*
* Check if we are over our maximum process limit, but be sure to
* exclude root. This is needed to make it possible for login and
* friends to set the per-user process limit to something lower
* than the amount of processes root is running. -- Rik
*/
if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur
&& !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE))
goto bad_fork_free;
Начиная с C99, также стало возможным использовать синтаксис // из C++, обозначающий однострочный комментарий.
Наличие комментариев к блокам позволяет визуально обозначить структурные прорывы, т.е. допустимые нарушения правила структурного программирования с одним входом/одним выходом , как в следующем примере:
static Edge edge_any(Node n, Node m) {
// Returns whether any edge is between nodes $n and $m.
Edge e;
for (e=n->edges; e; e=e->next) {
if (e->dst == m) {
/*********/ return e; } }
for (e=m->edges; e; e=e->next) {
if (e->dst == n) {
/*****/ break; } }
return e; }
Во многих языках, где нет блочного комментария, например awk , вы можете использовать последовательности разделителей операторов, например ; вместо. Но это невозможно в языках, использующих отступы как жесткое указание предполагаемой структуры блоков, таких как Python .
Конфигурация Cisco IOS и IOS-XE [ править ]
( Восклицательный знак ! ) может использоваться для обозначения комментариев в режиме конфигурации маршрутизатора Cisco, однако такие комментарии не сохраняются в энергонезависимой памяти (которая содержит конфигурацию запуска) и не отображаются командой «show run». . [41] [42]
Можно вставить удобочитаемый контент, который на самом деле является частью конфигурации и может быть сохранен в NVRAM стартовой конфигурации с помощью:
- Команда «описание», используемая для добавления описания в конфигурацию интерфейса или соседа . BGP
- Параметр «имя», чтобы добавить примечание к статическому маршруту.
- Команда «замечание» в списках доступа
! Paste the text below to reroute traffic manually
config t
int gi0/2
no shut
ip route 0.0.0.0 0.0.0.0 gi0/2 name ISP2
no ip route 0.0.0.0 0.0.0.0 gi0/1 name ISP1
int gi0/1
shut
exit
КолдФьюжн [ править ]
ColdFusion использует комментарии, аналогичные комментариям HTML , но вместо двух тире использует три. Эти комментарии улавливаются движком ColdFusion и не выводятся в браузер.
Такие комментарии являются вложенными.
<!--- This prints "Hello World" to the browser.
<!--- This is a comment used inside the first one.
--->
--->
<cfoutput>
Hello World<br />
</cfoutput>
Д [ править ]
D использует комментарии в стиле C++, а также вложенные многострочные комментарии в стиле D, которые начинаются с '/+' и заканчиваются '+/'.
// This is a single-line comment.
/* This is a multiline comment.
*/
/+ This is a
/+ nested +/
comment +/
Фортран IV [ править ]
Этот фрагмент кода Fortran IV демонстрирует, как используются комментарии в этом языке, который очень ориентирован на столбцы. Буква «C» в столбце 1 приводит к тому, что вся строка рассматривается как комментарий.
C
C Lines that begin with 'C' (in the first or 'comment' column) are comments
C
WRITE (6,610)
610 FORMAT(12H HELLO WORLD)
END
Обратите внимание, что столбцы строки в противном случае рассматриваются как четыре поля: с 1 по 5 — это поле метки, 6 означает, что строка воспринимается как продолжение предыдущего оператора; а декларации и заявления идут с 7 по 72.
Фортран 90 [ править ]
Этот фрагмент кода Фортрана демонстрирует, как в этом языке используются комментарии, причем сами комментарии описывают основные правила форматирования.
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!* All characters after an exclamation mark are considered as comments *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
program comment_test
print '(A)', 'Hello world' ! Fortran 90 introduced the option for inline comments.
end program
Хаскелл [ править ]
Комментарии к строкам в Haskell начинаются с «--» (два дефиса) до конца строки, а многострочные комментарии начинаются с «{-» и заканчиваются «-}».
{- this is a comment
on more lines -}
-- and this is a comment on one line
putStrLn "Wikipedia" -- this is another comment
Haskell также предоставляет грамотный метод программирования комментариев, известный как «Птичий стиль». [43] При этом все строки, начинающиеся с >, интерпретируются как код, все остальное считается комментарием. Еще одним требованием является то, что вы всегда должны оставлять пустую строку до и после блока кода:
In Bird-style you have to leave a blank before the code.
> fact :: Integer -> Integer
> fact 0 = 1
> fact (n+1) = (n+1) * fact n
And you have to leave a blank line after the code as well.
Грамотное программирование также можно выполнять на Haskell, используя LaTeX . Вместо стиля Ричарда Берда можно использовать среду кода: В стиле LaTeX это эквивалентно приведенному выше примеру: среда кода может быть определена в преамбуле LaTeX. Вот простое определение:
\usepackage{verbatim}
\newenvironment{code}{\verbatim}{\endverbatim}
позже в
% the LaTeX source file
The \verb|fact n| function call computes $n!$ if $n\ge 0$, here is a definition:\\
\begin{code}
fact :: Integer -> Integer
fact 0 = 1
fact (n+1) = (n+1) * fact n
\end{code}
Here more explanation using \LaTeX{} markup
Ява [ править ]
Этот фрагмент кода Java показывает комментарий к блоку, используемый для описания setToolTipText метод. Форматирование соответствует стандартам Sun Microsystems Javadoc . Комментарий предназначен для чтения процессором Javadoc.
/**
* This is a block comment in Java.
* The setToolTipText method registers the text to display in a tool tip.
* The text is displayed when the cursor lingers over the component.
*
* @param text The string to be displayed. If 'text' is null,
* the tool tip is turned off for this component.
*/
public void setToolTipText(String text) {
// This is an inline comment in Java. TODO: Write code for this method.
}
JavaScript [ править ]
JavaScript использует // для начала комментариев и /* */ для многострочных комментариев.
// A single line JavaScript comment
var iNum = 100;
var iTwo = 2; // A comment at the end of line
/*
multi-line
JavaScript comment
*/
Луа [ править ]
В языке программирования Lua используются двойные дефисы. --, для однострочных комментариев аналогично языкам Ada , Eiffel , Haskell , SQL и VHDL . В Lua также есть блочные комментарии, которые начинаются с --[[ и работать до закрытия ]]
Например:
--[[A multi-line
long comment
]]
print(20) -- print the result
Распространенный метод закомментирования фрагмента кода, [44] заключается в заключении кода между --[[ и
--]], как показано ниже:
--[[
print(10)
--]]
-- no action (commented out)
В этом случае можно повторно активировать код, добавив в первую строку один дефис:
---[[
print(10)
--]]
--> 10
В первом примере --[[ в первой строке начинается длинный комментарий, а в последней строке два дефиса
все еще внутри этого комментария. Во втором примере последовательность ---[[ начинается обычный однострочный
комментарий, чтобы первая и последняя строки стали независимыми комментариями. В этом случае print является
внешние комментарии. В этом случае последняя строка становится самостоятельным комментарием, так как начинается с --.
Длинные комментарии в Lua могут быть более сложными, о чем вы можете прочитать в разделе «Длинные строки» см. « Программирование на Lua » .
МАТЛАБ [ править ]
В языке программирования MATLAB символ «%» обозначает однострочный комментарий. Многострочные комментарии также доступны через скобки %{ и %} и могут быть вложенными, например
% These are the derivatives for each term
d = [0 -1 0];
%{
%{
(Example of a nested comment, indentation is for cosmetics (and ignored).)
%}
We form the sequence, following the Taylor formula.
Note that we're operating on a vector.
%}
seq = d .* (x - c).^n ./(factorial(n))
% We add-up to get the Taylor approximation
approx = sum(seq)
Nim [ edit ]
Ним использует символ «#» для встроенных комментариев. Многострочные комментарии к блоку открываются с помощью '#[' и закрываются с помощью ']#'. Многострочные комментарии к блокам могут быть вложенными.
В Nim также есть комментарии к документации, в которых используются смешанные Markdown и ReStructuredText разметки . Во встроенных комментариях к документации используется символ «##», а комментарии к многострочным блокам документации открываются с помощью «##[» и закрываются с помощью «]##». Компилятор может генерировать документацию HTML , LaTeX и JSON на основе комментариев к документации. Комментарии к документации являются частью абстрактного синтаксического дерева и могут быть извлечены с помощью макросов. [45]
## Documentation of the module *ReSTructuredText* and **MarkDown**
# This is a comment, but it is not a documentation comment.
type Kitten = object ## Documentation of type
age: int ## Documentation of field
proc purr(self: Kitten) =
## Documentation of function
echo "Purr Purr" # This is a comment, but it is not a documentation comment.
# This is a comment, but it is not a documentation comment.
OCaml [ править ]
OCaml использует вложенные комментарии, что полезно при комментировании блока кода.
codeLine(* comment level 1(*comment level 2*)*)
Паскаль, Дельфи [ править ]
В Pascal и Delphi комментарии разделяются символом '{ ... }'. Строки комментариев также могут начинаться с '\\' . В качестве альтернативы для компьютеров, которые не поддерживают эти символы, допускается использование символов «(* ... *)». [46]
В Никлауса Вирта более современном семействе языков (включая Modula-2 и Oberon ) комментарии разделяются символом «(* ... *)». [47] [48]
Например:
(* test diagonals *)
columnDifference := testColumn - column;
if (row + columnDifference = testRow) or
.......
Комментарии могут быть вложенными. // может быть включено в {}, а {} может быть включено в (**).
Перл [ править ]
Комментарии к строкам в Perl и многих других языках сценариев начинаются с символа решетки (#).
# A simple example
#
my $s = "Wikipedia"; # Sets the variable s to "Wikipedia".
print $s . "\n"; # Add a newline character after printing
Вместо обычной конструкции комментирования блоков Perl использует Plain Old Documentation — язык разметки для грамотного программирования . [49] например: [50]
=item Pod::List-E<gt>new()
Create a new list object. Properties may be specified through a hash
reference like this:
my $list = Pod::List->new({ -start => $., -indent => 4 });
See the individual methods/properties for details.
=cut
sub new {
my $this = shift;
my $class = ref($this) || $this;
my %params = @_;
my $self = {%params};
bless $self, $class;
$self->initialize();
return $self;
}
Р [ править ]
R поддерживает только встроенные комментарии, начинающиеся с символа решетки (#).
# This is a comment
print("This is not a comment") # This is another comment
Raku [ edit ]
Raku (ранее называвшийся Perl 6) использует те же строчные комментарии и комментарии документации POD, что и обычный Perl (см. раздел Perl выше), но добавляет настраиваемый тип блочных комментариев: «многострочные/встроенные комментарии». [51]
Они начинаются с символа решетки, за которым следует обратный апостроф, а затем какой-либо открывающий символ скобки и заканчиваются соответствующим символом закрывающей скобки. [51] Содержимое может не только занимать несколько строк, но также может быть встроено в строку.
#`{{ "commenting out" this version
toggle-case(Str:D $s)
Toggles the case of each character in a string:
my Str $toggled-string = toggle-case("mY NAME IS mICHAEL!");
}}
sub toggle-case(Str:D $s) #`( this version of parens is used now ){
...
}
PHP [ править ]
Комментарии в PHP могут быть либо в стиле C++ (как встроенными, так и блочными), либо использовать хэши. PHPDoc — это стиль, адаптированный из Javadoc, который является общим стандартом документирования кода PHP.
Начиная с PHP 8, знак # может означать комментарий только в том случае, если за ним сразу не следует '['. В противном случае это будет означать атрибут функции, который действует до ']':
/**
* This class contains a sample documentation.
*
* @author Unknown
*/
#[Attribute]
class MyAttribute {
const VALUE = 'value';
// This is an inline comment. It starts with '//', like in C++.
private $value;
# This is a Unix-style inline comment, which starts with '#'.
public function __construct($value = null) {
$this->value = $value;
}
/*
This is a multiline comment.
These comments cannot be nested.
*/
}
PowerShell [ править ]
Комментарии в Windows PowerShell
# Single line comment
Write-Host "Hello, World!"
<# Multi
Line
Comment #>
Write-Host "Goodbye, world!"
Питон [ править ]
Встроенные комментарии в Python используют символ решетки (#), как в двух примерах этого кода:
# This program prints "Hello World" to the screen
print("Hello World!") # Note the new syntax
Блочные комментарии, определенные в этой статье, технически не существуют в Python. [52] Можно использовать простой строковый литерал, представленный строкой в тройных кавычках: [53] но не игнорируется интерпретатором так же, как комментарий «#». [52] В приведенных ниже примерах строки в тройных двойных кавычках действуют как комментарии, но также рассматриваются как строки документации :
"""
Assuming this is file mymodule.py, then this string, being the
first statement in the file, will become the "mymodule" module's
docstring when the file is imported.
"""
class MyClass:
"""The class's docstring"""
def my_method(self):
"""The method's docstring"""
def my_function():
"""The function's docstring"""
Руби [ править ]
Встроенные комментарии в Ruby начинаются с символа #.
Чтобы создать многострочный комментарий, необходимо поместить «=begin» в начале строки, а затем все, что начинается с «=end», игнорируется. Включение пробела после знака равенства в этом случае приводит к синтаксической ошибке.
puts "This is not a comment"
# this is a comment
puts "This is not a comment"
=begin
whatever goes in these lines
is just for the human reader
=end
puts "This is not a comment"
SQL [ править ]
Стандартные комментарии в SQL состоят только из одной строки и состоят из двух тире:
-- This is a single line comment
-- followed by a second line
SELECT COUNT(*)
FROM Authors
WHERE Authors.name = 'Smith'; -- Note: we only want 'smith'
-- this comment appears after SQL code
В качестве альтернативы синтаксис формата комментариев, идентичный стилю «блочного комментария», используемому в синтаксисе C и Java, поддерживается Transact-SQL , MySQL , SQLite , PostgreSQL и Oracle . [54] [55] [56] [57] [58]
MySQL также поддерживает комментарии от символа решетки (#) до конца строки.
Свифт [ править ]
Однострочные комментарии начинаются с двух косых черт (//):
// This is a comment.
Многострочные комментарии начинаются с косой черты, за которой следует звездочка (/*), и заканчиваются звездочкой, за которой следует косая черта (*/):
/* This is also a comment
but is written over multiple lines. */
Многострочные комментарии в Swift могут быть вложены в другие многострочные комментарии. Вы пишете вложенные комментарии, начиная блок многострочных комментариев, а затем запуская второй многострочный комментарий внутри первого блока. Затем закрывается второй блок, а затем первый блок:
/* This is the start of the first multiline comment.
/* This is the second, nested multiline comment. */
This is the end of the first multiline comment. */
XML (или HTML) [ править ]
Комментарии в XML (или HTML) вводятся с помощью
<!--
и может распространяться на несколько строк до терминатора,
-->
Например,
<!-- select the context here -->
<param name="context" value="public" />
Для совместимости с SGML внутри комментариев не допускается строка «--» (двойной дефис).
Проблемы безопасности [ править ]
На интерпретируемых языках комментарии доступны для просмотра конечному пользователю программы. В некоторых случаях, например, в «закомментированных» разделах кода, это может представлять собой уязвимость безопасности . [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 .
- ^ Смит, Т. (1991). Промежуточные принципы и методы программирования с использованием Паскаля . Бельмонт: Западный паб. компании 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 г.