Programmers вики
Advertisement

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

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

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

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

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

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

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

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

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

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

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

Примердокументирующего комментария:

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

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

Advertisement