Что такое комментарии в программировании

Иллюстрация исходного кода Java с комментариями пролога. Обозначенными красным цветом, и встроенными комментариями зеленогоцвета . Код программы выделен синимцветом .

В компьютерном программированиикомментарий-это понятное программисту объяснение или аннотация в исходном коде компьютерной программы. Они добавляются с целью облегчения понимания исходного кода людьми и. Как правило. Игнорируются компиляторами и интерпретаторами. Синтаксис комментариев в различных языках программирования значительно различается.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Нет ' документации. Доступной по проблеме поведения сервера. Поэтому просто кодируйте вокруг нее. vtx = server.mappath() 

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

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

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

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

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

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

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

  идентификатор ресурса=>>   

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

Метаданные

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

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

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

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

Отладка

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

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

 if (opt.equals ()) opt_enabled = true; /*  if (opt.equals (  opt_debug = true;  */ if (opt.equals ()) opt_verbose = true; 

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

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

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

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

Примеры генераторов документации включают программы Javadoc для использования с Java, Ddoc для D, Doxygen для C, C++, Java, IDL, Visual Expert для PL/SQL, Transact-SQL, PowerBuilder и PHPDoc для PHP. Формы docstring поддерживаются Python, Lisp, Elixirи Clojure.]

C#, F# и Visual Basic .NET реализует аналогичную функцию под названием IntelliSense из скомпилированной сборки .NET.[19]

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

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

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

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

Два примера такого направления интерпретатора:

  • Unix shebang#!– используется в первой строке скрипта для указания на используемый интерпретатор.
  • например, Python PEP 263.]

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

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

Несколько похожим является использование комментариев в языке Си для сообщения компилятору о том. Что операторе case был сделан намеренно:

switch (command) { case CMD_SHOW_HELP_AND_EXIT: do_show_help(); /* Fall through */ case CMD_EXIT: do_exit(); break; case CMD_OTHER: do_other(); break; /* ... etc. ... */ } 

Добавление такого /* Fall thru */комментария для читателей-людей было уже общим соглашением. Но в 2017 году компилятор gcc начал искать эти (или другие признаки преднамеренного намерения). И они не будут найдены. Издавал: [23]

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

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

Снятие стресса

Иногда программисты добавляют комментарии. Чтобы снять стресс. Комментируя инструменты разработки. Конкурентов. Работодателей. Условия работы или качество самого кода. Возникновение этого явления легко увидеть по онлайн-ресурсам. Отслеживающим ненормативную лексику в исходном коде.[25]

Нормативные взгляды

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

[править]

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

Между этими взглядами находится утверждение. Что комментарии сами по себе ни полезны, ни вредны. И важно то. Что они правильны и синхронизированы с исходным кодом. А также опущены. Если они излишни, чрезмерны. Трудны в обслуживании или инымобразом бесполезны.]

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

Уровень детализации

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

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

 Строка s = ; /* Присваивает переменной s значение  

Однако такой уровень детализации не был бы уместен в контексте производственного кода или других ситуаций. Связанных с опытными разработчиками. Такие рудиментарные описания несовместимы с руководящим принципом: кроме того. Для профессиональных сред кодирования уровень детализации обычно хорошо определен для удовлетворения конкретных требований к производительности. Определяемых бизнес-операциями.[31]

Существует множество стилистических альтернатив. Доступных при рассмотрении того. Как комментарии должны появляться в исходном коде. Для более крупных проектов. В которых участвует команда разработчиков. Стили комментариев либо согласовываются до начала проекта. Либо развиваются в соответствии с соглашением или необходимостью по мере роста проекта. Обычно программисты предпочитают стили. Которые являются последовательными. Не препятствующими. Легко изменяемыми и трудно ломаемыми.[34]

[править]

Следующие фрагменты кода на языке Си демонстрируют лишь крошечный пример того. Как комментарии могут варьироваться стилистически. Но при этом передавать одну и ту же основную информацию:

/* Это тело комментария.   */ 
/***************************\ * * * Это тело комментария. * * Вариант второй. * * * \***************************/ 

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

Консультант по программному обеспечению и технологический комментатор Аллен Голуб[35] — один из экспертов. Который выступает за выравнивание левых краев комментариев:[36]

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

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

[править]

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

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

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

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

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

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

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

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

  • ОШИБКА – известная ошибка, которую необходимо исправить.
  • FIXME – должен быть исправлен.
  • ХАК – обходной путь.
  • ТОДО – что-то надо делать.
  • UNDONE – разворот или
  • XXX – предупреждайте других программистов о проблемном или ошибочном коде

Примеры

Сравнение

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

Ада

Язык программирования Ada использует

Например:

 -- задача диспетчера воздушного движения принимает запросы на взлет и посадку  тип задачи Контроллера (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

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

Например:

⍝ Теперь сложите числа: ca+b ⍝ сложение 

В диалектах. Имеющих примитивы ((внутри или отдельными операторами в виде игнорируемых строк:

d2×c 'где' ca+ 'связанный' b 

AppleScript

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

(* Эта программа отображает приветствие. *) on greet(myGreeting) display dialog myGreeting &  end greet - Показать приветствие greet() 

БАЗОВЫЙ

В этом классическом раннем базовом фрагменте кода ключевое слово REM () используется для добавления комментариев.

10 REM Эта БАЗОВАЯ программа показывает использование операторов PRINT и GOTO. 15 REM Он заполняет экран фразой  20 PRINT  30 GOTO 20 

В более поздних версиях Microsoft BASICs. Включая 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) Обрабатывает Button1.Click "Следующий код выполняется. Когда пользователь нажимает кнопку в окне программы". rem comments still exist. MessageBox.Show("Hello, World") 'Показать всплывающее окно с приветствием End Sub End Class 

C

Этот фрагмент кода на языке Си демонстрирует использование комментария пролога или условного оператора. Комментарий объясняет ключевые термины и понятия и включает в себя короткую подпись программиста. Который является автором кода.

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

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

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

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

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

  • Команда соседа BGP
  • Параметр
  • Команда
! Вставьте текст ниже. Чтобы перенаправить трафик вручную 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

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

   Hello Worldbr   

Fortran IV

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

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

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

Fortran 90

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

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

Хаскелл

{- это комментарий  - и это комментарий к одной строке putStrLn  - это еще один комментарий 

Haskell также предлагает грамотный метод программирования комментариев. Известный как [43]Одним из дополнительных требований является то. Что вы всегда оставляете пустую строку до и после блока кода:

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

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

\usepackage{verbatim} \newenvironment{code}{\verbatim}{\endverbatim} 

позже в

% исходный файл LaTeX Вызов \verb|fact n| function вычисляет $n!$ if $n\ge 0$, вот определение:\\ \begin{code} fact :: Integer  Integer fact 0 = 1 fact (n+1) = (n+1) * fact n \end{code} Вот еще одно объяснение использования разметки \LaTeX 

Java

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

/**  * Это блочный комментарий в Java.  * Метод setToolTipText регистрирует текст для отображения в подсказке инструмента.  * Текст отображается при наведении курсора на компонент.  *  * @param text-Строка для отображения. Если значение 'text' равно null,  то * подсказка инструмента для этого компонента отключена.  */ public void setToolTipText(String text) { // Это встроенный комментарий в Java. TODO: Написать код для этого метода. } 

JavaScript

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

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

Lua

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

Например:

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

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

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

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

---[[ print(10) --]]  

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

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

MATLAB

В языке программирования MATLAB символ

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

Ним

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

У Nim также есть комментарии к документации. Которые используют смешанные разметки Markdown и reStructuredText. Встроенные комментарии документации используют’##’. А многострочные блочные комментарии документации открываются с помощью ‘##[‘ и закрываются с помощью ‘]##’. Компилятор может генерировать документацию HTML , LaTeX и JSON из комментариев к документации. Комментарии к документации являются частью абстрактного синтаксического дерева и могут быть извлечены с помощью макросов.[45]

## Документация модуля *reStructuredText* и **MarkDown** # Это комментарий. Но это не комментарий к документации. type Kitten = object ## Documentation of type age: int ## Documentation of field proc purr(self: Kitten) = ## Documentation of function echo  # Это комментарий. Но это не комментарий к документации. # Это комментарий. Но это не комментарий к документации. 

OCaml

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

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

Паскаль

В семействе языков паскаля Никлауса Вирта (включая Modula-2 и Oberon) комментарии открываются с ‘(*’ и завершаются ‘*)’.

например:

(* тестовые диагонали *) columnDifference := testColumn - column; if (row + columnDifference = testRow) or ....... 

[46]

Perl

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

# Простой пример #  my $s = ; # Устанавливает переменную s в  print $s . ; # Добавить символ новой строки после печати 

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

 Создайте новый объект списка. Свойства могут быть заданы через хэш -ссылку следующим образом:  Дополнительные сведения см. в разделе Отдельные методы/свойства. =cut sub new { my $this = shift; my $class = ref($this) || $this; my %params = @_; my $self = {%params}; bless $self, $class; $selfinitialize(); return $self; } 

R

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

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

Раку

Raku (ранее называвшийся Perl 6) использует те же строчные комментарии и комментарии документации POD. Что и обычный Perl (см. раздел Perl выше). Но добавляет настраиваемый тип блочных комментариев: ]

Они начинаются с хэш-символа. За которым следует обратная галочка. А затем какой-то открывающий символ брекетинга и заканчиваются соответствующим закрывающим символом брекетинга. Содержимое может не только охватывать несколько строк. Но и быть встроено в строку.

#`{{  переключателя-корпус(ул.:д $с) переключает дело каждого символа в строке:  моя Стр $переключать строки = переключение регистра( }} суб переключения-корпус(ул.:д ) #`( Эта версия скобок. Используется и сейчас )

PHP

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

PowerShell

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

# Однострочный комментарий Write-Host    Многострочный  Write-Host  

Python

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

# Эта программа печатает  печати() # Обратите внимание на новый синтаксис 

Блочные комментарии. Как они определены в этой статье. Технически не существуют в Python.[50] Можно использовать голый строковый литерал, представленный строкой в тройных кавычках, но интерпретатор не игнорирует его так же. Как комментарий[50] В приведенных ниже примерах строки в тройных двойных кавычках действуют таким образом как комментарии. Но также рассматриваются как док-строки:

 Предполагая. Что это файл mymodule.py. То эта строка. Будучи первым оператором в файле. Станет docstring модуля  при импорте файла.  class MyClass:  def my_method(self):  def my_function():  

Рубин

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

Однострочный комментарий: (строка начинается с хэша

puts  # this is a comment puts  

Многострочное комментирование: (комментарии идут между ключевыми словами

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

SQL

Стандартные комментарии в SQL представлены в однострочной форме с использованием двух тире:

-- Это однострочный комментарий -- за ним следует вторая строка SELECT COUNT(*) FROM Authors WHERE Authors.name = 'Smith'; -- Примечание: нам нужен только 'smith' -- этот комментарий появляется после кода SQL 

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

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

Swift

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

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

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

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

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

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

XML

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

и может распространяться на несколько линий. Пока терминатор,

Например,

  имя param= value=  

Вопросы безопасности

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

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

  1. ^ Для целей данной статьи комментарии языка программирования рассматриваются как неотличимые от комментариев. Которые появляются в языках разметки, конфигурационных файлах и других подобных контекстах. Кроме того, язык разметки часто тесно интегрирован с кодом языка программирования. Особенно в контексте генерации кода. См., например,, Гангули. Мадхушри (2002). Использование Jsp. Нью-Йорк: Уайли. ISBN 978-0-471-21974-3., Hewitt. Eben (2003). Java для разработчиков Coldfusion. Верхняя Седловина реки: Образование Пирсона. ISBN 978-0-13-046180-3.
  2. ^ Диксит, Дж.Б. (2003). Основы вычислительной техники и программирования на языке Си. Публикации Лакшми. ISBN 978-81-7008-882-0.
  3. ^ Хайэм, Десмонд (2005). Руководство по MATLAB. СИАМ. ISBN 978-0-89871-578-1.
  4. ^ Vermeulen, Al (2000). Элементы стиля Java. Издательство Кембриджского университета. ISBN 978-0-521-77768-1.
  5. ^ b c . 2000-03-04. Проверено 2007-07-24.
  6. ^ W. R., Dietrich (2003). Прикладное распознавание образов: Алгоритмы и реализация на языке C++. Спрингер. ISBN 978-3-528-35558-6. предлагает точки зрения на правильное использование комментариев в исходном коде. стр. 66.
  7. ^ b Кейс, Джессика (2003). Руководство по программной инженерии. CRC Press. ISBN 978-0-8493-1479-7. Обсуждаются комментарии и
  8. ^ . Архивирован с оригинала 2007-07-14. Проверено 2007-07-24.
  9. ^ b Niederst. Jennifer (2006). Веб-дизайн в двух словах: Краткий справочник по настольномукомпьютеру . О’Рейли. ISBN 978-0-596-00987-8.Иногда разница между Нидерст указывает на одну из таких ситуаций, заявляя: Чтобы избежать этой проблемы. Используйте вместо этого раздел XML CDATA.
  10. ^ См., например,, Уинн-Пауэлл. Род (2008). Mac Os X для фотографов: Оптимизированный рабочий процесс изображения для пользователя Mac. Оксфорд: Фокусная пресса. ISBN 978-0-240-52027-8. страница 243
  11. ^ Лэмб, Линда (1998). Изучение редактора VI. Севастополь: O’Reilly & Associates. ISBN 978-1-56592-426-0. описывает использование синтаксиса modeline в конфигурационных файлах Vim.
  12. ^ См., например,, Berlin. Daniel (2006). Практическая Подрывная деятельность. Второе издание. Беркли: Апрес. ISBN 978-1-59059-753-8.
  13. ^ Эмблер, Скотт (2004). The Object Primer: Agile Model-Driven Development with UML 2.0. Издательство Кембриджского университета. ISBN 978-1-397-80521-8.
  14. ^ Определение функции с помощью docstring в Clojure
  15. ^ Мураха. C# 2005. p. 56.
  16. ^ c2: HotComments
  17. ^ . Руби. ruby-lang.org. Проверено 5 декабря 2018года .
  18. ^ . Python.org. Проверено 5 декабря 2018года .
  19. ^ Полячек, Марек (2017-03-10). . Разработчик Red Hat. Красная Шляпа. Извлечено 10 февраля 2019года .
  20. ^ , Lisa Eadicicco, 27 Марта 2014 Года. Businessinsider.com.au
  21. ^ (см., Например, Подсчет клятв Linux).
  22. ^ Гудлифф, Пит (2006). Кодовое ремесло. Сан-Франциско: Никакого Крахмального пресса. ISBN 978-1-59327-119-0.
  23. ^ Smith, T. (1991). Промежуточные Принципы и методы программирования с использованием языка Паскаль. Belmont: West Pub. Co. ISBN 978-0-314-66314-6.
  24. ^ См., например,, Koletzke. Peter (2000). Oracle Developer Advanced Forms & Reports. Беркли: Осборн/Макгроу-Хилл. ISBN 978-0-07-212048-6. страница 65.
  25. ^ Морелли, Ральф (2006). Java, Java, Java: объектно-ориентированное решение задач. Колледж Прентис Холл. ISBN 978-0-13-147434-5.
  26. ^ b . Извлечено 2007-07-24. Руководящие принципы Javadoc указывают. Что комментарии имеют решающее значение для платформы. Кроме того, соответствующий уровень детализации довольно четко определен:
  27. ^ Yourdon, Edward (2007). Методы построения и проектирования программ. Несуществующие комментарии могут затруднить понимание кода. Но комментарии могут быть вредными. Если они устарели, избыточны. Неправильны или иным образом затрудняют понимание предполагаемого назначения исходного кода.
  28. ^ Dewhurst, Stephen C (2002). C++ Gotchas: Избегание распространенных проблем в кодировании и дизайне. Эддисон-Уэсли Профессионал. ISBN 978-0-321-12518-7.
  29. ^ . Архивирован с оригинала 2007-08-08. Проверено 2007-07-24.
  30. ^ . Архивирован с оригинала 2007-07-20. Проверено 2007-07-24.
  31. ^ Аллен Голуб, Достаточно веревки, чтобы выстрелить себе в ногу, ISBN 0-07-029689-8, 1995, McGraw-Hill
  32. ^ Кен Томпсон. . Извлечено 2017-07-21.
  33. ^ , Python Software Foundation
  34. ^ , используя комментарии
  35. ^ , msdn.microsoft.com
  36. ^ . Cisco Learning Network (дискуссионный форум).
  37. ^ .
  38. ^ . haskell.org.
  39. ^ . www.Lua.org. Проверено 2017-11-08.
  40. ^ macros.extractdocommentsandrunnables
  41. ^ . www.freepascal.org. Проверено 2017-09-20.
  42. ^ . Проверено 2011-09-12.
  43. ^ . Проверено 2011-09-12.
  44. ^ b . Проверено 2017-04-06.
  45. ^ b . Проверено 25 февраля 2019года . Тройные кавычки рассматриваются как обычные строки. За исключением того. Что они могут охватывать несколько строк. Под регулярными строками я подразумеваю. Что если они не назначены переменной. То будут немедленно собраны мусором. Как только этот код будет выполнен. следовательно. Они не игнорируются интерпретатором так же. Как и комментарий #a.
  46. ^ , 11 сентября 2011 года. Guido van Rossum
  47. ^ Talmage, Ronald R. (1999). Microsoft SQL Server 7. Издательство ISBN 978-0-7615-1389-6.
  48. ^ . Корпорация Получено 2 января 2020года .
  49. ^ . Консорциум SQLite. Проверено 2 января 2020года .
  50. ^ . Глобальная группа разработки PostgreSQL. Проверено 2 января 2020года .
  51. ^ . Корпорация Получено 2 января 2020года .

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

Внешние ссылки