Документирование сценариев
Документирование сценариев является очень важным этапом при разработке приложений. Комментарии позволяют описать, что именно и как выполняет сценарий. Чем больше, сложнее и замысловатее код сценария, тем большее значение приобретает документирование. Проработав двадцать часов над сценарием, вы будете уверены, что он навеки останется в вашей памяти. Однако по прошествии двух лет, когда необходимо будет пересмотреть код сценария, вы его совсем не узнаете. Также вполне возможна ситуация, когда действительно кто-то другой захочет переделать код сценария, а в это время вы будете недоступны, отдыхая на Багамах.
Комментарии (comments) представляют собой заметки, вставляемые в код сценария. При этом они игнорируются интерпретатором РНР и предназначены для пользователей. Комментарии в сценарии могут быть произвольной длины. Их общий синтаксис имеет следующий вид:
/* текст комментариев
еще комментарии */
Когда интерпретатор РНР встречает в сценарии символы начала комментария (/*), весь последующий код игнорируется вплоть до символов * /.
Очень часто разработчики добавляют комментарии в начало сценариев, чтобы дать о нем краткую информацию и указать, какие функции он выполняет. Рассмотрим следующий пример:
/* имя сценария: hello.php
описание: отображает строку "Здравствуй, мир!"
на Web-странице
автор: Программист Джон
дата создания: 02/01/08
дата изменения: 03/15/08
*/
В языке РНР комментарии можно использовать и в сокращенной форме. Для этого можю использовать символ решетки (#) либо два символа косой черты (//). Они позволяют закомментировать целую строку. Например:
# Строка комментариев 1
/ / Строка комментариев 2
Символы # и / / можно также использовать в строке кода, указывая тем самым на начало комментария. Это особенно полезно для описания работы отдельного оператора. Рассмотрим следующий пример:
echo "Привет"; // это мой первый оператор вывода
Следует отметить, что интерпретатор РНР не включает комментарии в HTML-код, передаваемый впоследствии браузеру, так что пользователь их увидеть не сможет.
Иногда очень полезно использовать комментарии в качестве заголовка разделов кода, например:
/* Проверяет, исполнилось ли покупателю 18 лет */
/* Сохраняет информацию в базе данных */
/* Осуществляет поиск указанного файла */
Иногда следует выделить комментарии, чтобы заострить на них внимание. Это можно сделать следующим образом:
###########################
# Дважды проверьте этот раздел #
###########################
Используйте комментарии так часто, как того требует ситуация. Однако, с другой стороны, не стоит ими злоупотреблять: большое количество комментариев может резко снизить их ценность. Их лучше всего использовать для описания различных разделов кода сценария или в случае нестандартного (или неочевидного) подхода к написанию программы. Например, комментарий, поясняющий работу оператора echo, является лишним, поскольку и так понятно, для чего он предназначен. Если смысл кода очевиден, не следует загромождать его лишними комментариями.
Внимательно следите за тем, чтобы не использовать в сценарии вложенные комментарии. В этом случае код РНР будет работать некорректно. Рассмотрим следующий пример:
/* Первый комментарий
/* Вложенный комментарий */
*/
Найдя символы начала комментария, /*, интерпретатор РНР будет игнорировать код до тех пор, пока не встретит символы */. Поэтому будет проигнорирован и второй набор символов /*. Таким образом, будет закомментировано все, что находится между первыми символами /* и */. Дойдя до второго набора символов */, интерпретатор РНР выдаст сообщение об ошибке, поскольку он не интерпретирует их как символы окончания комментария.
