7.3. Использование комментариев
Известно, как важны комментарии для документирования исходного текста и насколько удобнее и привлекательнее делают его понятные имена. Написанная вами программа, состоящая из большого количества строк, будет идеально работать и без каких-либо комментариев. Возможно, некоторое время вы будете подробно помнить каждую строчку программы и ее смысл. Но потом вы это забудете, так как сам код программы вам больше изменять не придется.
Но представьте ситуацию, при которой с развитием новых продуктов либо технологий доступа и обработки информации у вас возникнет необходимость изменить программу. Тут вам можно будет только посочувствовать. Без комментариев будет довольно сложно разобраться в программе, а тем более, если понадобится изменить программу не вам, а вашему знакомому или товарищу по работе. На то, чтобы понять, как же работает этот код, придется затратить немалое количество часов. Чтобы помочь вам избежать подобной ситуации, в этом параграфе излагаются некоторые несложные соглашения об именах и комментариях.
Комментарии во всех языках программирования призваны помочь исчерпывающе документировать исходный текст
В РНР, впрочем, как и в С, допустимы две разновидности комментариев. Комментарии традиционного стиля начинаются знаком /* и заканчиваются знаком */. Например:
/* это комментарий в одну строку*/
/* этот комментарий занимает
несколько строк*/
Комментарии этого типа не могут быть вложенными, т. е. конструкция
/* один комментарий, /* а здесь начинается другой */*/
недопустима. Эта ситуация часто возникает, когда комментарий используется в процессе
Комментарии второго типа — односторонние — начинаются знаком // и заканчиваются в конце строки, в которой этот знак появляется, т. е. эти комментарии действуют только на протяжении одной строки. Если же вам надо написать несколько строк комментариев, просто начинайте каждую новую строку с //:
// этот комментарий занимает
// несколько строк
Односторонние комментарии не обязательно занимают всю строку и могут следовать за текстом кода, например:
<?php
while (!feof($fp) // цикл будет продолжаться,
// пока не найдена
{ // закрывающая скобка
// при недостигнутом конце
} // строки
Заметьте также, что комментарий типа // можно включить в комментарии /*...* /. Если вы ограничитесь использованием в тексте только комментариев типа //, то при отладке вы сможете использовать /*...*/для того, чтобы закомментировать большие фрагменты текста, не беспокоясь об ошибках компиляции из-за вложенных комментариев. Также если комментарий маленький и занимает только одну строчку, можно поставить / /и таким образом легко закомментировать любую строчку до ее конца. Как обычно, пробелы, символы табуляции и перевод строки просто игнорируются и могут применяться для улучшения удобочитаемости кода РНР.
ВНИМАНИЕ
Классы тоже могут использовать односторонние комментарии — краткое описание функциональности, заключенной в классе.
