Комментарии в скриптах

Содержание PHP-скрипта представляет собой код на РНР или на HTML, ко­торый предназначен для обработки компьютером. Но есть также разделы, кото­рые предназначены только для человека — комментарии.

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

В РНР существует три типа комментариев. Первый тип позволяет распола­гать комментарии в нескольких строках, начиная их символами /* и заканчи­вая символами */, например:

<?php
/* Скрипт начинается с вывода
приветственного сообщения для пользователя */ echo "Доброе утро!";
?>

Для повышения выразительности можно заключить в /*...*/ каждую строку комментария, например:

<?php
/* Скрипт начинается с вывода */
/* приветственного сообщения для пользователя */ echo "Доброе утро!";
?>

Следует иметь ввиду, что вложенные комментарии недопустимы. Следую­щий код является ошибочным:

<?php
/* Скрипт начинается с вывода /* приветственного сообщения */
для пользователя */
echo "Доброе утро!";
?>

Ошибка заключается в том, что после начала комментария РНР ищет после­довательность символов */, закрывающую комментарий, не обращая внимание на символы /*, даже если они встретятся.

Остальные два типа комментариев являются однострочными. Они начинают­ся с символов // или # и продолжаются до конца строки:

<?php
//Скрипт начинается с вывода
#   приветственного сообщения для пользователя echo "Доброе утро!";
?>

Этот тип комментариев удобен тем, что их можно размещать справа от кода, например:

<?php
echo "Доброе утро!";     // Вывод первого сообщения echo  "Добрый день!";     # Вывод второго сообщения
?>

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

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