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

Комментарии в разметке Википедии см. Справка: разметка Wiki # Форматирование символов и WP: КОММЕНТАРИЙ.
Иллюстрация Ява исходный код с пролог комментарии, указанные в красный и в соответствии комментарии в зеленый. Программный код в синий.

В компьютерное программирование, а комментарий является понятным для программиста объяснением или аннотация в исходный код из компьютерная программа. Они добавляются с целью облегчения понимания исходного кода людьми и обычно игнорируются компиляторы и переводчики.[1][2] В синтаксис комментариев в разных языках программирования значительно различается.

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

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

Обзор

Комментарии обычно форматируются как заблокировать комментарии (также называется комментарии к прологу или поток комментариев) или строковые комментарии (также называется встроенные комментарии).[3]

Заблокировать комментарии разграничивать область исходного кода, которая может охватывать несколько строк или часть одной строки. Этот регион обозначен Начните разделитель и конец разделитель. Некоторые языки программирования (например, MATLAB ) позволяют рекурсивно вкладывать комментарии блоков друг в друга, но другие (например, Ява ) не.[4][5][6]

Комментарии к строке либо начинаются с разделителя комментариев и продолжаются до конца строки, либо, в некоторых случаях, начинаются с определенного столбца (смещения строки символов) в исходном коде и продолжаются до конца строки.[6]

Некоторые языки программирования используют как блочные, так и строчные комментарии с разными разделителями комментариев. Например, C ++ есть комментарии блока, разделенные /* и */ которые могут охватывать несколько строк и комментарии к строкам, разделенные //. Другие языки поддерживают только один тип комментариев. Например, Ада комментарии - это строковые комментарии: они начинаются с -- и продолжаем до конца строки.[6]

Использует

Вопрос о том, как лучше использовать комментарии, является предметом спора; разные комментаторы высказывали различные, а иногда и противоположные точки зрения.[7][8]Есть много разных способов написания комментариев, и многие комментаторы предлагают противоречивые советы.[8]

Планирование и анализ

Комментарии можно использовать как форму псевдокод обрисовать намерение до написания фактического кода. В этом случае он должен объяснять логику кода, а не сам код.

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

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

Описание кода

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

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

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

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

Алгоритмическое описание

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

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

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

Включение ресурсов

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

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

<!-- begin: wsf_resource_nodes --><ресурс id ="ProcessDiagram000"> HostApp (Главный_процесс)    |    Vscript.wsf (app_cmd) -> ClientApp (async_run, batch_process)                |                |                V         mru.ini (mru_history) ]]></resource>

Хотя эту идентичную диаграмму можно было бы легко включить в качестве комментария, пример иллюстрирует один случай, когда программист может отказаться использовать комментарии как способ включения ресурсов в исходный код.[13]

Метаданные

Основная статья: Метаданные

Комментарии в компьютерной программе часто хранят метаданные о файле программы.

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

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

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

Отладка

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

Ниже приведен пример комментирования кода в целях исключения:

 если (выбрать.равно ("е"))   opt_enabled = правда; /* если (opt.equals ("d"))   opt_debug = true; */ если (выбрать.равно ("v"))    opt_verbose = правда;

Приведенный выше фрагмент кода предполагает, что программист по какой-то причине решил отключить опцию отладки.

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

Автоматическое создание документации

Основная статья: Генератор документации

Инструменты программирования иногда хранят документацию и метаданные в комментариях.[14] Они могут включать позиции вставки для автоматического включения файла заголовка, команды для установки файла подсветка синтаксиса Режим,[15] или файл номер ревизии.[16] Эти комментарии к функциональным элементам управления также обычно называют аннотации. Хранение документации в комментариях к исходному коду рассматривается как один из способов упростить процесс документации, а также повысить шансы на то, что документация будет обновляться с изменениями в коде.[17]

Примеры генераторов документации включают программы Javadoc для использования с Ява, Ddoc за D, Doxygen за C, C ++, Ява, IDL, Визуальный эксперт за PL / SQL, Transact-SQL, PowerBuilder и PHPDoc за PHP. Формы строка документации поддерживаются Python, Лисп, Эликсир, и Clojure.[18]

C #, F # и Visual Basic .NET реализовать аналогичную функцию под названием «Комментарии XML», которые читаются IntelliSense из собранных .СЕТЬ сборка.[19]

Расширение синтаксиса

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

Директива использует

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

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

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

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

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

В некоторой степени похоже на использование комментариев в C, чтобы сообщить компилятору, что "провал" по умолчанию в заявление о случае сделано сознательно:

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

Вставив такой / * Падение * / комментарий для читателей был уже обычным явлением, но в 2017 году gcc компилятор начал искать эти (или другие признаки преднамеренного намерения) и, если они не были найдены, выдал: «предупреждение: этот оператор может не пройти».[23]

Многие редакторы и Иды буду читать комментарии в специальном формате. Например, функция "модельная линия" Vim; который изменил бы обработку вкладок при редактировании источника с этим комментарием, включенным в верхней части файла:

# vim: tabstop = 8 expandtab 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]

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

Использование / * и * / в качестве разделителей комментариев к блокам было унаследовано от PL / I в языке программирования B, непосредственном предшественнике языка программирования C.[37]

Комментарии к строке

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

В этом примере игнорируется весь текст от символов ASCII // до конца строки.

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

Часто такой комментарий должен начинаться слева и длиться до всей строки. Однако на многих языках также можно поставить комментарий в соответствии с помощью командной строки, чтобы добавить к ней комментарий - как в этом примере Perl:

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

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

Теги

Программисты могут использовать неформальные теги в комментариях, чтобы помочь в индексировании распространенных проблем. Затем их можно будет найти с помощью обычных инструментов программирования, таких как Unix grep полезность или даже выделенный синтаксисом в текстовые редакторы. Иногда их называют "кодовыми метками".[38][39] или «жетоны».[40]

Такие теги сильно различаются, но могут включать:

  • БАГ - известный ошибка это следует исправить.
  • FIXME - надо поправить.
  • HACK - обходной путь.
  • TODO - что-то нужно сделать.
  • UNDONE - разворот или «откат» предыдущего кода.
  • XXX - предупреждать других программистов о проблемном или вводящем в заблуждение коде

Примеры

Сравнение

Основная статья: Сравнение языков программирования (синтаксис) § Комментарии

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

Ада

В Ада язык программирования использует знак «-» для обозначения комментария до конца строки.

Например:

  - задача авиадиспетчера принимает запросы на взлет и посадку   задача тип Контроллер (My_Runway: Runway_Access) является      - записи задач для синхронной передачи сообщений      вход Request_Takeoff (МНЕ БЫ: в Airplane_ID; Отгул: вне Runway_Access);      вход Request_Approach(МНЕ БЫ: в Airplane_ID; Подход: вне Runway_Access);   конец Контроллер;

APL

APL использует ⍝ чтобы указать комментарий до конца строки.

Например:

⍝ Теперь сложите числа:c←а+б ⍝ дополнение

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

d←2×c ⊣'куда'⊢ c←а+ 'граница'⊢ б

AppleScript

Этот раздел AppleScript код показывает два стиля комментариев, используемых на этом языке.

(*Эта программа отображает приветствие.*)на приветствовать(myGreeting)     диалог отображения myGreeting & " Мир!"конец приветствовать- Показать приветствиеприветствовать("Здравствуйте")

БАЗОВЫЙ

В этой классической ранней БАЗОВЫЙ фрагмент кода REM ("Замечание") ключевое слово используется для добавления комментариев.

10REM Эта BASIC программа показывает использование операторов PRINT и GOTO.15REM На экране появляется фраза "HELLO".20РАСПЕЧАТАТЬ"ПРИВЕТ"30ПЕРЕЙТИ К20

Позже Microsoft BASIC, включая Быстрый базовый, Q Базовый, Visual Basic, Visual Basic .NET, и Сценарий VB; и в таких потомках, как FreeBASIC и Гамбас любой текст в строке после символа '(апостроф) также рассматривается как комментарий.

Пример в Visual Basic .NET:

Общественные Учебный класс Форма 1    Частный Sub Button1_Click(отправитель Так как Объект, е Так как EventArgs) Ручки Button1.Нажмите        'Следующий код выполняется, когда пользователь        'нажимает кнопку в окне программы.        rem комментарии все еще существуют.        Окно сообщения.Шоу("Привет, мир") 'Показать всплывающее окно с приветствием    Конец SubКонец Учебный класс

C

Этот C фрагмент кода демонстрирует использование вступительного комментария или «блочного комментария» для описания цели Условный оператор. Комментарий объясняет ключевые термины и концепции и включает короткую подпись программиста, создавшего код.

 /*  * Проверьте, не превысили ли мы максимальный лимит процесса, но обязательно  * исключить root. Это необходимо для того, чтобы можно было войти и  * друзья, чтобы установить предел процесса для каждого пользователя на что-то меньшее  * чем количество запущенных процессов. - Рик  */ если (atomic_read(&п->пользователь->процессы) >= п->Rlim[RLIMIT_NPROC].rlim_cur     && !способный(CAP_SYS_ADMIN) && !способный(CAP_SYS_RESOURCE))     перейти к bad_fork_free;

Начиная с C99, также стало возможным использовать синтаксис // из C ++, указывающий на однострочный комментарий.

Конфигурация Cisco IOS и IOS-XE

В восклицательный знак (!) можно использовать для пометки комментариев в режиме конфигурации маршрутизатора Cisco, однако такие комментарии нет сохранено в энергонезависимая память (который содержит конфигурацию запуска), и они не отображаются командой "show run".[41][42]

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

  • Команда "description", используемая для добавления описания к конфигурации интерфейса или BGP сосед
  • Параметр "name", чтобы добавить примечание к статическому маршруту.
  • Команда "замечание" в списках доступа
! Вставьте текст ниже, чтобы перенаправить трафик вручнуюconfig tint gi0 / 2no shutip route 0.0.0.0 0.0.0.0 gi0 / 2 name ISP2no ip route 0.0.0.0 0.0.0.0 gi0 / 1 name ISP1int gi0 / 1shutexit

Холодный синтез

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

 <!--- This prints "Hello World" to the browser. ---> <cfoutput>   Привет мир<br /> </cfoutput>

Фортран IV

Этот Фортран IV Фрагмент кода демонстрирует, как используются комментарии на этом языке, который очень ориентирован на столбцы. Буква «C» в столбце 1 означает, что вся строка рассматривается как комментарий.

CC Строки, начинающиеся с 'C' (в первом столбце или столбце "комментарий"), являются комментариями.C ЗАПИСЫВАТЬ (6,610)  610 ФОРМАТ(12ЧАС ПРИВЕТ МИР) КОНЕЦ

Обратите внимание, что в противном случае столбцы строки обрабатываются как четыре поля: от 1 до 5 - это поле метки, 6 заставляет строку считаться продолжением предыдущего оператора; а декларации и заявления идут с 7 по 72.

Фортран 90

Этот Фортран Фрагмент кода демонстрирует, как используются комментарии на этом языке, причем сами комментарии описывают основные правила форматирования.

!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *! * Все символы после восклицательного знака считаются комментариями *!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *программа comment_test    Распечатать '(А)', 'Привет, мир' ! В Fortran 90 появилась возможность встроенных комментариев.конец программы

Haskell

Комментарии к строке в Haskell начинаются с символа «-» (два дефиса) до конца строки, а комментарии к нескольким строкам начинаются с символа «{-» и заканчиваются знаком «-}».

{- это комментарийна других строках -}- а это комментарий к одной строкеputStrLn «Википедия»  - это еще один комментарий

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

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

Грамотное программирование также можно выполнить на Haskell, используя Латекс. Кодовую среду можно использовать вместо стиля Ричарда Берда: В Латекс style это эквивалентно приведенному выше примеру, среда кода может быть определена в преамбуле LaTeX. Вот простое определение:

 usepackage{дословно} newenvironment{код}{ дословно}{ endverbatim}

позже

% исходный файл LaTeXВ глагол| факт п | вызов функции вычисляет $п!$ если $п ge0$, вот определение:\\начинать{код}факт :: Целое число -> Целое числофакт 0 = 1факт (п+1) = (п+1) * факт пконец{код}Здесь больше объяснений с использованием Латекс{} разметка

Ява

Этот Ява фрагмент кода показывает комментарий блока, используемый для описания setToolTipText метод. Форматирование соответствует Sun Microsystems Javadoc стандарты. Комментарий предназначен для чтения процессором Javadoc.

/** * Это блочный комментарий в Java. * Метод setToolTipText регистрирует текст для отображения во всплывающей подсказке. * Текст отображается, когда курсор задерживается над компонентом. * * @param text Строка для отображения. Если текст равен нулю, * подсказка для этого компонента отключена. */общественный пустота setToolTipText(Строка текст) {    // Это встроенный комментарий в Java. ЗАДАЧА: Напишите код для этого метода.}

JavaScript

JavaScript использует // перед комментариями и / * * / для многострочных комментариев.

// Однострочный комментарий JavaScriptвар iNum = 100;вар iTwo = 2; // Комментарий в конце строки/*многострочныйКомментарий JavaScript*/

Lua

В Lua язык программирования использует двойные дефисы, --, для однострочных комментариев аналогично Ада, Эйфель, Haskell, SQL и VHDL языков. В Lua также есть блочные комментарии, которые начинаются с --[[ и бежать до закрытия ]]

Например:

- [[Многострочныйдлинный комментарий]]Распечатать(20)   - распечатать результат

Распространенный метод комментирования фрагмента кода,[44] заключить код между --[[ и--]], как показано ниже:

--[[печать (10)--]]- никаких действий (закомментировано)

В этом случае можно повторно активировать код, добавив один дефис в первую строку:

---[[Распечатать(10)--]]--> 10

В первом примере --[[ в первой строке начинается длинный комментарий, а два дефиса в последней строке все еще находятся внутри этого комментария. Во втором примере последовательность ---[[ запускает обычный однострочный комментарий, так что первая и последняя строки становятся независимыми комментариями. В этом случае Распечатать это внешние комментарии. В этом случае последняя строка становится независимым комментарием, так как начинается с --.

Длинные комментарии в Lua могут быть более сложными, чем эти, как вы можете прочитать в разделе «Длинные строки» c.f. Программирование на Lua.

MATLAB

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

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

Ним

Ним для встроенных комментариев используется символ '#'. Комментарии к многострочным блокам открываются с помощью '# [' и закрываются с помощью '] #. Комментарии к многострочным блокам могут быть вложенными.

У Нима также есть комментарии к документации, в которых используются смешанные Markdown и ReStructuredText Комментарии во встроенной документации используют '##', а комментарии многострочной блочной документации открываются с '## [' и закрываются '] ##. Компилятор может генерировать HTML, Латекс и JSON документацию из комментариев к документации. Комментарии к документации являются частью абстрактное синтаксическое дерево и может быть извлечен с помощью макросов.[45]

## Документация модуля * ReSTructuredText * и ** MarkDown **# Это комментарий, но не комментарий документации.тип Котенок = объект  ## Типовая документация  возраст: int  ## Документация поляproc мурлыкать(себя: Котенок) =  ## Документация по функциям  эхо "Мурлыкать"  # Это комментарий, но не комментарий документации.# Это комментарий, но не комментарий документации.

OCaml

OCaml использует вложенные комментарии, что полезно при комментировании блока кода.

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

Паскаль

У Никлауса Вирта паскаль семейство языков (включая Модула-2 и Оберон ), комментарии открываются знаком '(*' и завершаются знаком '*)'.

Например:

(* тестовые диагонали *)columnDifference := testColumn - столбец;если (ряд + columnDifference = testRow) или    .......

В современных диалектах Паскаля вместо них используются '{' и '}'.[46]

Perl

Комментарии к строке в Perl, и многие другие языки сценариев, начинаются с символа решетки (#). 

# Простой пример# мой $ s = «Википедия»; # Устанавливает для переменной s значение "Википедия".Распечатать $ s . " п";     # Добавить символ новой строки после печати

Вместо обычной конструкции блочного комментирования Perl использует Обычная старая документация, язык разметки для грамотное программирование,[47] например:[48]

= элемент Pod :: List-E  new ()Создайте новый объект списка. Свойства могут быть указаны через хешссылка вроде этого:  мой $ list = Pod :: List-> new ({-start => $., -indent => 4});См. Подробности об отдельных методах / свойствах.= вырезатьсуб новый {    мой $ это = сдвиг;    мой $ класс = ссылка($ это) || $ это;    мой % params = @_;    мой $ self = {% params};    благослови $ self, $ класс;    $ self->инициализировать();    вернуть $ self;}

р

р поддерживает только встроенные комментарии, начинающиеся с символа решетки (#).

# Это комментарийРаспечатать("Это не комментарий")  # Это еще один комментарий

Раку

Раку (ранее назывался Perl 6) использует те же строковые комментарии и комментарии документации POD, что и обычные Perl (см. раздел Perl выше), но добавляет настраиваемый тип блочного комментария: «многострочные / встроенные комментарии».[49]

Они начинаются с символа решетки, за которым следует обратная кавычка, а затем некоторый открывающий символ скобки и заканчиваются соответствующим закрывающим символом скобки.[49] Контент может не только занимать несколько строк, но также может быть встроен в строку.

# `{{" комментируем "эту версию toggle-case (Стр .: D $ s)Переключает регистр каждого символа в строке:  мой Str $ toggled-string = toggle-case («МОЕ ИМЯ - МИХАЭЛ!»);}}суб тумблер(Ул: D $ s) # `(сейчас используется эта версия parens){    ...}

PHP

Комментарии в PHP может быть либо в стиле C ++ (как встроенный, так и блочный), либо использовать хэши. PHPDoc - это стиль, адаптированный из Javadoc, и является общим стандартом для документирования кода PHP.

PowerShell

Комментарии в Windows PowerShell

# Однострочный комментарийЗапись-хост "Привет, мир!"<# Мульти   Линия   Комментарий #>Запись-хост "Прощай мир!"

Python

Встроенные комментарии в Python используйте символ решетки (#), как в двух примерах этого кода:

# Эта программа выводит на экран "Hello World"Распечатать("Привет мир!")  # Обратите внимание на новый синтаксис

Блочные комментарии, как определено в этой статье, технически не существуют в Python.[50] Голый строковый литерал может использоваться строка, заключенная в тройные кавычки,[51] но не игнорируется интерпретатором так же, как комментарий "#".[50] В приведенных ниже примерах строки с тройными двойными кавычками действуют таким образом как комментарии, но также рассматриваются как строки документации:

"""Предположим, что это файл mymodule.py, тогда эта строка, являющаясяпервый оператор в файле, станет модулем "mymodule"docstring при импорте файла."""класс Мой класс:    "" "Строка документации класса" ""    def my_method(себя):        "" "Строка документации метода" ""def моя_функция():    "" "Строка документации функции" ""

Рубин

Комментарии в Рубин.

Однострочный комментарий: (строка начинается с решетки "#")

ставит "Это не комментарий"# это комментарийставит "Это не комментарий"

Многострочные комментарии: (комментарии помещаются между ключевыми словами "начало" и "конец")

ставит "Это не комментарий"= начатьвсе, что идет в этих строкахтолько для человеческого читателя= конецставит "Это не комментарий"

SQL

Стандартные комментарии в SQL имеют однострочную форму с двумя дефисами:

- Это однострочный комментарий- за которым следует вторая строкаВЫБРАТЬ СЧИТАТЬ(*)       ИЗ Авторы       КУДА Авторы.имя = 'Смит'; - Примечание: нам нужен только «кузнец»                                     - этот комментарий появляется после кода SQL

В качестве альтернативы синтаксис формата комментария, идентичный стилю «блочного комментария», используемому в синтаксисе для C и Java, поддерживается Transact-SQL, MySQL, SQLite, PostgreSQL, и Oracle.[52][53][54][55][56]

MySQL также поддерживает комментарии от символа решетки (#) до конца строки.

Быстрый

Однострочные комментарии начинаются с двух косых черт (//):

// Это комментарий.

Многострочные комментарии начинаются с косой черты, за которой следует звездочка (/ *), и заканчиваются звездочкой, за которой следует косая черта (* /):

/ * Это тоже комментарий но написано на нескольких строках. * /

Многострочные комментарии в Swift могут быть вложены в другие многострочные комментарии. Вы пишете вложенные комментарии, начиная с многострочного блока комментариев, а затем начиная второй многострочный комментарий внутри первого блока. Затем закрывается второй блок, за ним следует первый блок:

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

XML

Комментарии в XML (или HTML) вводятся с 

<!--

и может растягиваться на несколько строк до терминатора, 

-->

Например,

<!-- select the context here --><параметр имя ="контекст" значение ="общественный" />

Проблемы с безопасностью

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

Смотрите также

Примечания и ссылки

  1. ^ Исходный код можно разделить на программный код (который состоит из машинно-переводимых инструкций); и Комментарии (которые включают удобочитаемые заметки и другие виды аннотаций в поддержку программного кода).Пенни Грабб, Армстронг Таканг (2003). Сопровождение программного обеспечения: концепции и практика. World Scientific. С. 7, пожалуйста, начало120–121. ISBN  978-981-238-426-3.
  2. ^ Для целей данной статьи комментарии на языке программирования рассматриваются как неотличимые от комментариев, которые появляются в языки разметки, файлы конфигурации и другие подобные контексты. Более того, язык разметки часто тесно интегрирован с кодом языка программирования, особенно в контексте генерация кода. См., Например, Гангули, Мадхушри (2002). Использование Jsp. Нью-Йорк: Вили. ISBN  978-0-471-21974-3., Хьюитт, Эбен (2003). Java для разработчиков Coldfusion. Верхняя река Сэдл: образование Пирсона. ISBN  978-0-13-046180-3.
  3. ^ Диксит, Дж. Б. (2003). Основы работы с компьютером и программирование на C. Публикации Лакшми. ISBN  978-81-7008-882-0.
  4. ^ Хайэм, Десмонд (2005). MATLAB Руководство. СИАМ. ISBN  978-0-89871-578-1.
  5. ^ Вермёлен, Эл (2000). Элементы стиля Java. Издательство Кембриджского университета. ISBN  978-0-521-77768-1.
  6. ^ а б c «Использование правильного комментария в Java». 2000-03-04. Получено 2007-07-24.
  7. ^ В. Р., Дитрих (2003). Прикладное распознавание образов: алгоритмы и реализация на C ++. Springer. ISBN  978-3-528-35558-6. предлагает точки зрения на правильное использование комментариев в исходном коде. п. 66.
  8. ^ а б Киз, Джессика (2003). Справочник по разработке программного обеспечения. CRC Press. ISBN  978-0-8493-1479-7. обсуждает комментарии и «Наука о документации» стр. 256.
  9. ^ а б c Элементы стиля программирования, Керниган & Plauger
  10. ^ а б Код завершен, МакКоннелл
  11. ^ Спинеллис, Диомидис (2003). Чтение кода: перспектива открытого исходного кода. Эддисон-Уэсли. ISBN  978-0-201-79940-8.
  12. ^ «CodePlotter 1.6 - Добавляйте и редактируйте диаграммы в коде с помощью этого инструмента, похожего на Visio». Архивировано из оригинал на 2007-07-14. Получено 2007-07-24.
  13. ^ а б Нидерст, Дженнифер (2006). Краткий обзор веб-дизайна: краткое руководство для настольных ПК. О'Рейли. ISBN  978-0-596-00987-8.Иногда разница между «комментарием» и другими элементами синтаксиса языка программирования или разметки влечет за собой тонкие нюансы. Нидерст указывает на одну из таких ситуаций, заявив: «К сожалению, программное обеспечение XML считает комментарии неважной информацией и может просто удалить комментарии из документа перед его обработкой. Чтобы избежать этой проблемы, используйте вместо этого раздел XML CDATA».
  14. ^ См., Например, Винн-Пауэлл, Род (2008). Mac Os X для фотографов: оптимизированный рабочий процесс с изображениями для пользователей Mac. Оксфорд: Focal Press. ISBN  978-0-240-52027-8. стр. 243
  15. ^ Лэмб, Линда (1998). Изучение редактора VI. Севастополь: O'Reilly & Associates. ISBN  978-1-56592-426-0. описывает использование синтаксиса модельной строки в файлах конфигурации Vim.
  16. ^ См., Например, Берлин, Даниэль (2006). Практическая Subversion, второе издание. Беркли: АПресс. ISBN  978-1-59059-753-8. стр.168.
  17. ^ Эмблер, Скотт (2004). Учебник по объектам: гибкая разработка на основе моделей с использованием UML 2.0. Издательство Кембриджского университета. ISBN  978-1-397-80521-8.
  18. ^ Определение функции со строкой документации в Clojure
  19. ^ Мурах. C # 2005. п. 56.
  20. ^ c2: Горячие комментарии
  21. ^ "кодировка класса". Рубин. ruby-lang.org. Получено 5 декабря 2018.
  22. ^ «PEP 263 - Определение кодировок исходного кода Python». Python.org. Получено 5 декабря 2018.
  23. ^ Полачек, Марек (10.03.2017). "-Wimplicit-fallthrough в GCC 7". Разработчик Red Hat. Красная Шапка. Получено 10 февраля 2019.
  24. ^ «Программисты Microsoft скрывали кучу ненормативной лексики в раннем программном коде», Лиза Эдичико, 27 марта 2014 г., businessinsider.com.au
  25. ^ (см., например, Счетчик присяги в Linux ).
  26. ^ Гудлифф, Пит (2006). Code Craft. Сан-Франциско: Пресса без крахмала. ISBN  978-1-59327-119-0.
  27. ^ Смит, Т. (1991). Принципы и методы промежуточного программирования с использованием Паскаля. Бельмонт: Западный паб. Co. ISBN  978-0-314-66314-6.
  28. ^ См., Например, Колецке, Питер (2000). Расширенные формы и отчеты Oracle Developer. Беркли: Осборн / Макгроу-Хилл. ISBN  978-0-07-212048-6. стр.65.
  29. ^ «Худшая практика - плохие комментарии». Получено 2007-07-24.
  30. ^ Морелли, Ральф (2006). Java, Java, Java: объектно-ориентированное решение проблем. Колледж Прентис Холл. ISBN  978-0-13-147434-5.
  31. ^ а б «Как писать комментарии к документам для инструмента Javadoc». Получено 2007-07-24. Руководства Javadoc указывают, что комментарии имеют решающее значение для платформы. Кроме того, соответствующий уровень детализации довольно четко определен: «Мы тратим время и усилия, сосредоточенные на указании граничных условий, диапазонов аргументов и угловых случаев, а не на определении общих терминов программирования, написании концептуальных обзоров и включении примеров для разработчиков».
  32. ^ Йордон, Эдвард (2007). Методы структуры и дизайна программы. Университет Мичигана. 013901702X.Несуществующие комментарии могут затруднить понимание кода, но комментарии могут быть вредными, если они устарели, избыточны, неверны или иным образом затрудняют понимание предполагаемой цели исходного кода.
  33. ^ Дьюхерст, Стивен С. (2002). Подсказки C ++: как избежать общих проблем в кодировании и дизайне. Эддисон-Уэсли Профессионал. ISBN  978-0-321-12518-7.
  34. ^ «Стиль кодирования». Архивировано из оригинал на 2008-08-08. Получено 2007-07-24.
  35. ^ "Аллен Голуб". Архивировано из оригинал на 2007-07-20. Получено 2007-07-24.
  36. ^ Аллен Голуб, Веревки достаточно, чтобы прострелить себе ногу, ISBN  0-07-029689-8, 1995, Макгроу-Хилл
  37. ^ Кен Томпсон. «Ссылка пользователей на B». Получено 2017-07-21.
  38. ^ «PEP 0350 - Кодовые метки», Python Software Foundation
  39. ^ «Никогда не забывайте ничего до, после и во время кодирования», Использование комментариев "codetag" в качестве продуктивных остатков
  40. ^ «Использование списка задач», msdn.microsoft.com
  41. ^ "Оставить комментарий в running-config". Cisco Learning Network (дискуссионный форум).
  42. ^ «Руководство по настройке управления файлами конфигурации, Cisco IOS XE Release 3S (серия ASR 900)».
  43. ^ «Грамотное программирование». haskell.org.
  44. ^ «Программирование на Lua 1.3». www.Lua.org. Получено 2017-11-08.
  45. ^ macros.extractDocCommentsAndRunnables
  46. ^ "Комментарии". www.freepascal.org. Получено 2017-09-20.
  47. ^ "perlpod - простой формат старой документации". Получено 2011-09-12.
  48. ^ «Pod :: ParseUtils - помощники для синтаксического анализа и преобразования POD». Получено 2011-09-12.
  49. ^ а б «Документация Perl 6 - Синтаксис (Комментарии)». Получено 2017-04-06.
  50. ^ а б «Базовый синтаксис Python 3». Получено 25 февраля 2019. Тройные кавычки рассматриваются как обычные строки, за исключением того, что они могут занимать несколько строк. Под обычными строками я подразумеваю, что если они не присвоены переменной, они будут немедленно собраны мусором, как только этот код будет выполнен. следовательно, интерпретатор не игнорирует их так же, как #a comment.
  51. ^ «Совет Python: вы можете использовать многострочные строки как многострочные комментарии», 11 сентября 2011 г., Гвидо ван Россум
  52. ^ Талмейдж, Рональд Р. (1999). Microsoft SQL Server 7. Прима Паблишинг. ISBN  978-0-7615-1389-6.
  53. ^ «Справочное руководство по MySQL 8.0». Корпорация Oracle. Получено 2 января, 2020.
  54. ^ «SQL в понимании SQLite». Консорциум SQLite. Получено 2 января, 2020.
  55. ^ «Документация по PostgreSQL 10.11». Группа глобального развития PostgreSQL. Получено 2 января, 2020.
  56. ^ "Справочник Oracle® Database SQL". Корпорация Oracle. Получено 2 января, 2020.
  57. ^ Андресс, Мэнди (2003). Выживание в безопасности: как интегрировать людей, процессы и технологии. CRC Press. ISBN  978-0-8493-2042-2.

дальнейшее чтение

внешняя ссылка