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

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

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

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

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

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

Комментарии часто используются для временного отключения части кода. В языках 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

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

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

                Комментарии используются для документирования кода. В следующем примере компилятор принимает комментарий:

                /* Comments can contain keywords such as for and while without generating errors. */ 

                Комментарии в коде могут находиться в той же строке, что и оператор:

                printf( "Hello\n" ); /* Comments can go here */ 

                Перед функциями или программными модулями можно вставлять блоки комментариев с описаниями.

                /* MATHERR.C illustrates writing an error routine * for math functions. */ 

                Так как комментарии не могут содержать вложенные комментарии, в этом примере возникает ошибка:

                /* Comment out this routine for testing /* Open file */ fh = _open( "myfile.c", _O_RDONLY ); . . . */ 

                Причина ошибки в том, что компилятор распознает первое сочетание символов, */ , расположенное после слов Open file , как конец комментария. Он пытается обработать оставшийся текст, а обнаружив символы */ за пределами комментария, выдает сообщение об ошибке.

                Хотя с помощью комментариев можно скрывать часть кода для тестирования, для этого есть полезная альтернатива: директивы препроцессора #if и #endif и условная компиляция. Дополнительные сведения см. в статье Preprocessor Directives (Директивы препроцессора) в справочника по препроцессору.

                Блок, относящийся только к системам Microsoft

                Компилятор Microsoft также поддерживает однострочные комментарии, перед которыми ставятся две косые черты ( // ). Эти примечания не могут быть расширены до второй строки.

                // This is a valid comment 

                Комментарии, начинающиеся с двух косых черт ( // ), заканчиваются следующим символом новой строки, которому не предшествует escape-символ. В следующем примере символу новой строки предшествует обратная косая черта ( \ ), создается escape-последовательность. Эта escape-последовательность заставляет компилятор обрабатывать следующую строку как часть предыдущей строки. Дополнительные сведения см. в статье Escape Sequences (Escape-последовательности).

                // my comment \ i++; 

                Поэтому оператор i++; скрыт комментарием.

                В Microsoft C расширения Microsoft по умолчанию включены. Отключить их можно при помощи параметра /Za.

                Завершение блока, относящегося только к системам Майкрософт

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

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

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

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

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

                Комментарии часто используются для временного отключения части кода. В языках 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 обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.

                Примечания

                См. также

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

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

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

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

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

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

                Похожие публикации:

                1. Как перевести страницу в edge
                2. Как перевести экспоненциальный формат в числовой в excel
                3. Как пригласить в группу в ватсапе
                4. Как установить определенную версию библиотеки python