Что такое комментарий в программировании
Перейти к содержимому

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

  • автор:

Комментарии (программирование)

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

Назначение комментариев

Большинство специалистов сходятся во мнении, что комментарии должны объяснять намерения программиста, а не код; то, что можно выразить на языке программирования, не должно выноситься в комментарии — в частности, надо использовать говорящие названия переменных, функций, классов, методов и пр., разбивать программу на лёгкие для понимания части, стремиться к тому, чтобы структура классов и структура баз данных были максимально понятными и прозрачными и т. д. Есть даже мнение (его придерживаются в экстремальном программировании и некоторых других гибких методологиях программирования), что если для понимания программы требуются комментарии — значит, она плохо написана.

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

Комментарии часто используются для временного отключения части кода. В языках C и C++, некоторые рекомендуют использовать с той же целью директивы препроцессора ( #if 0 … #endif ).

Однострочные и многострочные комментарии

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

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

Аннотации

Другой вид комментариев — аннотации — применяется в набросках доказательств правильности программ. Такие комментарии описывают состояние компьютера, когда программа в процессе выполнения достигнет точки, где расположен комментарий. Программа, снабжённая комментариями-аннотациями, называется аннотированной программой.

Автоматическая генерация документации

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

Специальным образом оформленные комментарии (т. н. документирующие комментарии) используются для автоматического создания документации, в первую очередь, к библиотекам функций или классов. Для этого используются генераторы документации, например, такие как javadoc [1] для языка Java, phpDocumentor для PHP [2] , doxygen [3] для C и C++ и др.

Документирующие комментарии как правило оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.

/** * Имя или краткое описание объекта * * Развернутое описание * * @имя_дескриптора значение * @return тип_данных */ 

В некоторых средах программирования (например, Eclipse, NetBeans, Python, Visual Studio) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций.

Трансляция программ

Во время трансляции комментарии распознаются на стадии лексического анализа (и, соответственно, считаются лексемами). Распознавание на стадии препроцессирования накладно и даже чревато ошибками; включение комментариев в синтаксические диаграммы практически невозможно.

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

  • Ассемблер
  • Форт
  • BASIC
  • BLITZ PLUS
  • BAT-файлы и команды DOS
  • пакетный файлLinux, QNX
  • C, C++, PHP, C#, Java и JavaScript
  • Кобол
  • Delphi (Object Pascal)
  • Fortran
  • HTML, XML, XHTML, wiki-разметка
  • Конфигурационные (ini) файлы
  • Файлы реестра Windows (REG)
  • Система аналитических вычислений Mathematica
  • Система аналитических вычислений Maple
  • Pascal, Modula-2, Modula-3, Oberon и ML
  • Perl
  • Python, различные варианты командных оболочек UNIX, AWK, sed, Tcl
  • PL/SQL
  • Ruby
  • Smalltalk
  • TeX, LaTeX, PostScript
  • Visual Basic
  • Lua

Специальные комментарии

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

Например в диалекте Турбо Паскаль псевдокомментарии и используются для отключения и включения стандартного контроля ошибок ввода-вывода. Похожие специальные комментарии используются в языке разметки HTML для указания типа SGML-документа, «экранирования» таблиц стилей и сценариев на языках JavaScript и VBScript:

Некоторые комментарии программисты используют в ходе своей работы. Подобные комментарии особенно полезны, когда над одним кодом работает несколько разработчиков. Так, комментарием TODO обычно помечают участок кода, который программист оставляет незавершённым, чтобы вернуться к нему позже. Комментарий FIXME помечает обнаруженную ошибку, которую решают исправить позже. Комментарий XXX обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.

Примечания

См. также

  • Условный комментарий
  • Документирующие комментарии
  • Концепции языков программирования

Учебники. Программирование для начинающих.

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

Programm.ws — это сайт, на котором вы можете почитать литературу по языкам программирования , а так-же посмотреть примеры работающих программ на С++, ассемблере, паскале и много другого..

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

Cамоучитель по Java

Глава 1. Встроенные типы данных, операции над ними

Комментарии

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

  • за двумя наклонными чертами подряд //, без пробела между ними, начинается комментарий, продолжающийся до конца строки;
  • за наклонной чертой и звездочкой /* начинается комментарий, который может занимать несколько строк, до звездочки и наклонной черты */ (без пробелов между этими знаками).

Комментарии очень удобны для чтения и понимания кода, они превращают программу в документ, описывающий ее действия. Программу с хорошими комментариями называют самодокументированной. Поэтому в Java введены комментарии третьего типа, а в состав JDK — программа javadoc , извлекающая эти комментарии в отдельные файлы формата HTML и создающая гиперссылки между ними: за наклонной чертой и двумя звездочками подряд, без пробелов, /** начинается комментарий, который может занимать несколько строк до звездочки (одной) и наклонной черты */ и обрабатываться программой javadoc . В такой комментарий можно вставить указания программе javadoc , которые начинаются с символа @.

Именно так создается документация к JDK.

Добавим комментарии к нашему примеру (листинг 1.2).

Листинг 1.2. Первая программа с комментариями

* Разъяснение содержания и особенностей программы.

* @author Имя Фамилия (автора)

* @version 1.0 (это версия программы)

// Следующий метод начинает выполнение программы

public static void main(String[] args)< // args не используются

/* Следующий метод просто выводит свой аргумент

* на экран дисплея */

System.out.println(«Hello, 21st Century World!»);

// Следующий вызов закомментирован,

// метод не будет выполняться

// System.out.println(«Farewell, 20th Century!»);

Звездочки в начале строк не имеют никакого значения, они написаны просто для выделения комментария. Пример, конечно, перегружен пояснениями (это плохой стиль), здесь просто показаны разные формы комментариев.

Комментарии в программировании

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

Назначение комментариев

Большинство специалистов сходятся во мнении, что комментарии должны объяснять намерения программиста, а не код; то, что можно выразить на языке программирования, не должно выноситься в комментарии — в частности, надо использовать говорящие названия переменных, функций, классов, методов и пр., разбивать программу на лёгкие для понимания части, стремиться к тому, чтобы структура классов и структура баз данных были максимально понятными и прозрачными и т. д. Есть даже мнение (его придерживаются в экстремальном программировании и некоторых других гибких методологиях программирования), что если для понимания программы требуются комментарии — значит, она плохо написана.

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

Комментарии часто используются для временного отключения части кода. В языках C и C++, некоторые рекомендуют использовать с той же целью директивы препроцессора ( #if 0 … #endif ).

Однострочные и многострочные комментарии

С точки зрения синтаксиса, существуют два вида комментариев. Многострочный комментарий может иметь любую длину, он отмечается специальными символами в начале и конце (например, /* */ ). Некоторые языки позволяют вложение многострочных комментариев, другие — нет. Однострочный комментарий отмечается специальным символом в начале (например, // ) и продолжается до конца строки. Обычно допускается вложение однострочных комментариев в другие, как одно- так и многострочные комментарии. Способы записи можно чередовать, с точки зрения семантики они одинаковы.

Аннотации

Другой вид комментариев — аннотации — применяется в набросках доказательств правильности программ. Такие комментарии описывают состояние компьютера, когда программа в процессе выполнения достигнет точки, где расположен комментарий. Программа, снабжённая комментариями-аннотациями, называется аннотированной программой.

Автоматическая генерация документации

Специальным образом оформленные комментарии (т. н. документирующие комментарии) используются для автоматического создания документации, в первую очередь, к библиотекам функций или классов. Для этого используются генераторы документации, например, такие как [1] для языка doxygen [2] для C и C++ и др. В некоторых средах программирования (например, Python) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций.

Трансляция программ

Во время трансляции комментарии распознаются на стадии лексического анализа (и, соответственно, считаются лексемами). Распознавание на стадии препроцессирования накладно и даже чревато ошибками; включение комментариев в синтаксические диаграммы практически невозможно.

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

  • Ассемблер
  • Форт
  • REM однострочный комментарий
    • BAT-файлы и команды :: однострочный комментарий
      • C, C++, C#, JavaScript
      • Кобол
      • Object Pascal)
      • Fortran
      • XML, wiki-разметка
      • Конфигурационные (ini) файлы
      • Система аналитических вычислений
        • Pascal, Modula-2, Modula-3, Oberon и < многострочный комментарий >
          • Python, различные варианты командных оболочек UNIX, sed,
            • PL/SQL
            • =end # однострочный комментарий
                • LaTeX,
                  • Visual Basic

                  Специальные комментарии

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

                  Например в диалекте Турбо Паскаль псевдокомментарии и используются для отключения и включения стандартного контроля ошибок ввода-вывода. Похожие специальные комментарии используются в языке разметки SGML-документа, «экранирования» таблиц стилей и сценариев на языках VBScript:

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

                  См. также

                  Wikimedia Foundation . 2010 .

                  Комментарии (C++)

                  Комментарий — это текст, который предназначен для программистов и не обрабатывается компилятором. Обычно комментарии используются для создания заметок к коду для дальнейшего использования. Компилятор обрабатывает их как пробел. При тестировании можно использовать примечания, чтобы сделать определенные строки кода неактивными; Однако директивы препроцессора лучше работают для этого, #if / #endif так как вы можете окружать код, содержащий комментарии, но не вложенные примечания.

                  Комментарии в C++ записываются одним из следующих способов:

                  • Символы /* (косая черта и звездочка), за которыми следует любая последовательность символов, включая переводы строки, после чего ставятся символы */ . Это тот же синтаксис, который используется в ANSI C.
                  • Символы // (две косые черты), за которыми следует любая последовательность символов. Символ перевода строки, непосредственно перед которым нет обратной косой черты, завершает комментарий, оформленный таким способом. Поэтому такие комментарии часто называют однострочными.

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

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *