Понимание комментариев PHP

Комментарии — это заметки, которые вы оставляете в исходном коде и которые PHP игнорирует при выполнении программы. Они существуют исключительно для людей — чтобы объяснить почему определённый фрагмент кода делает то, что делает, оставить напоминания или временно отключить код во время отладки. В этом руководстве рассматривается весь синтаксис комментариев, поддерживаемый PHP, когда использовать каждый из них, и практики, которые делают комментарии полезными, а не шумом.

В этой главе предполагается, что вы уже умеете писать базовый PHP. Если нет — сначала изучите главы Синтаксис PHP и Переменные PHP.

Что такое комментарии PHP?

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

PHP поддерживает три стиля комментариев, которые делятся на две группы:

• Однострочные комментарии, записываемые с помощью // или #.
• Многострочные (блочные) комментарии, записываемые с помощью /* ... */.

PHP унаследовал стили // и /* */ из C и Java, а стиль # — из shell-скриптов и Perl, поэтому какой бы язык вы ни использовали раньше, один из этих вариантов покажется вам знакомым.

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

Однострочный комментарий заставляет PHP игнорировать остаток текущей строки. PHP предоставляет два взаимозаменяемых маркера для этого: // (в стиле C) и # (в стиле shell). Они ведут себя одинаково — выберите один и оставайтесь последовательными в рамках проекта.

<?php
// This is a single-line comment (C-style)
echo "Hello, world!";

# This is also a single-line comment (shell-style)
echo " Goodbye!";

echo " Done."; // a comment can also follow code on the same line

Комментарий заканчивается на переносе строки, поэтому операторы echo всё равно выполняются. Приведённый выше скрипт выводит Hello, world! Goodbye! Done.

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

Многострочный комментарий начинается с /* и заканчивается на */. Всё между этими маркерами игнорируется, даже если это занимает много строк. Используйте его для более длинных объяснений или чтобы закомментировать блок кода сразу.

<?php
/* This is a multi-line comment.
   It can span as many lines as you need,
   which is handy for longer explanations. */
echo "Visible output";

/* You can also keep it on a single line */ echo " — still works";

Два оператора echo выводят Visible output — still works; всё внутри /* ... */ пропускается.

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

Зачем использовать комментарии PHP?

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

Как использовать комментарии PHP

Чтобы добавить комментарий в код PHP, просто начните строку с двух косых черт (для однострочных комментариев) или с косой черты и звёздочки (для многострочных комментариев). Важно выбирать подходящий тип комментария в зависимости от размера и сложности комментируемого кода.

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

Комментирование кода при отладке

Одно из наиболее практичных применений комментариев — временное отключение кода без его удаления. Добавьте // или # в начало строки или оберните несколько строк в /* ... */, чтобы исключить их из программы:

<?php
$total = 10 + 5;
// echo $total;        // disabled: don't print yet
echo "Total calculated";

Помните о правиле запрета вложенности: если код, который вы хотите отключить, уже содержит блок /* */, комментируйте его построчно с помощью //.

Документирующие комментарии (PHPDoc)

Помимо обычных комментариев, в экосистеме PHP существует соглашение о документировании под названием PHPDoc. Это блочный комментарий, начинающийся с /** (два звёздочки) и использующий теги @ для описания функций, параметров и возвращаемых значений. IDE и инструменты наподобие phpDocumentor читают их, чтобы обеспечить автодополнение и генерацию документации API.

<?php
/**
 * Adds two numbers together.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of the two numbers.
 */
function add($a, $b)
{
    return $a + $b;
}

echo add(2, 3); // 5

PHPDoc с точки зрения движка PHP — это обычный комментарий /* */, не имеющий эффекта во время выполнения, но следование этому соглашению делает ваши функции намного понятнее для редакторов и коллег. Вы будете активно встречать его в главе Функции PHP.

Лучшие практики использования комментариев PHP

Вот несколько лучших практик при работе с комментариями PHP:

• Используйте чёткий и лаконичный язык в комментариях
• Избегайте дублирования кода в комментариях — объясняйте почему, а не что
• Сосредоточьтесь на предоставлении информации, которая не сразу очевидна из кода
• Используйте подходящий уровень детализации в комментариях
• Поддерживайте актуальность комментариев по мере изменения кода — устаревший комментарий хуже, чем его отсутствие
• Отдавайте предпочтение говорящим именам переменных и функций перед комментариями, объясняющими неочевидные имена

Заключение

Комментарии PHP — незаменимый инструмент для разработчиков, позволяющий сделать код более понятным и удобным для сопровождения. PHP предоставляет три синтаксиса — // и # для однострочных, и /* ... */ для блочных — а также соглашение PHPDoc для документирования функций. Следуя лучшим практикам, изложенным в этой статье, вы сможете максимально эффективно использовать комментарии PHP и гарантировать, что ваш код будет хорошо задокументирован и понятен другим разработчикам.

Чтобы продолжить обучение, перейдите к главам Переменные PHP и Операторы PHP.

Практика