стр. 28-29

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

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

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

В PHP существует два вида комментариев:

1. Многострочные
2. Однострочные

Поговорим о них подробнее.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Когда пишут комментарии

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