Документирование сценариев

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

Комментарии (comments) представляют собой заметки, вставляемые в код сценария. При этом они игнорируются интерпретатором РНР и предназначены для пользователей. Комментарии в сценарии могут быть произвольной длины. Их общий синтаксис имеет следующий вид:

/* текст комментариев
еще комментарии */

Когда интерпретатор РНР встречает в сценарии символы начала комментария (/*), весь последующий код игнорируется вплоть до символов * /.

Очень часто разработчики добавляют комментарии в начало сценариев, чтобы дать о нем краткую информацию и указать, какие функции он выполняет. Рассмотрим следующий пример:

/* имя сценария: hello.php
    описание: отображает строку "Здравствуй, мир!"
    на Web-странице
    автор: Программист Джон
    дата создания: 02/01/08
    дата изменения: 03/15/08
*/

В языке РНР комментарии можно использовать и в сокращенной форме. Для этого можю использовать символ решетки (#) либо два символа косой черты (//). Они позволяют закомментировать целую строку. Например:

# Строка комментариев 1
/ / Строка комментариев 2

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

echo "Привет"; // это мой первый оператор вывода

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

Иногда очень полезно использовать комментарии в качестве заголовка разделов кода, например:

/* Проверяет, исполнилось ли покупателю 18 лет */
/* Сохраняет информацию в базе данных */
/* Осуществляет поиск указанного файла */

Иногда следует выделить комментарии, чтобы заострить на них внимание. Это можно сделать следующим образом:

###########################
# Дважды проверьте этот раздел #
###########################

Используйте комментарии так часто, как того требует ситуация. Однако, с другой стороны, не стоит ими злоупотреблять: большое количество комментариев может резко снизить их ценность. Их лучше всего использовать для описания различных разделов кода сценария или в случае нестандартного (или неочевидного) подхода к написанию программы. Например, комментарий, поясняющий работу оператора echo, является лишним, поскольку и так понятно, для чего он предназначен. Если смысл кода очевиден, не следует загромождать его лишними комментариями.

Внимательно следите за тем, чтобы не использовать в сценарии вложенные комментарии. В этом случае код РНР будет работать некорректно. Рассмотрим следующий пример:

/* Первый комментарий
    /* Вложенный комментарий */
*/

Найдя символы начала комментария, /*, интерпретатор РНР будет игнорировать код до тех пор, пока не встретит символы */. Поэтому будет проигнорирован и второй набор символов /*. Таким образом, будет закомментировано все, что находится между первыми символами /* и */. Дойдя до второго набора символов */, интерпретатор РНР выдаст сообщение об ошибке, поскольку он не интерпретирует их как символы окончания комментария.