Способы комментирования в PHP: от простых пометок до PHPDoc
Основные принципы комментирования PHP кода
Как пояснить отдельные строки или временно отключить часть кода?
Наиболее распространённый способ - использовать однострочные комментарии // или #, а также многострочные комментарии /* */. Они полностью игнорируются интерпретатором.
// Это однострочный комментарий
$name = 'PHP'; // комментарий после кода
/*
Многострочный комментарий
можно использовать для описания
или отключения блока кода
*/
echo $name;
Php комментарии в коде (комментарии в php коде)
Однострочные комментарии подходят для кратких пояснений. Многострочные - для подробных описаний или временного исключения блоков кода.
Типичная ошибка
Вложенные многострочные комментарии недопустимы. Например, такой код вызовет синтаксическую ошибку:
/*
echo 'внешний';
/* echo 'внутренний'; */
echo 'ещё';
*/
Php скрипт (php скрипт)
Внутренний */ закрывает внешний комментарий, а последний */ остаётся без открывающего. Решение - использовать if (false) { ... } или избегать вложения.
Как документировать функции и классы с помощью PHPDoc?
PHPDoc - это специальный формат многострочных комментариев, начинающихся с /**. Они содержат аннотации (@param, @return, @throws и другие) и используются для автоматической генерации документации и подсказок в IDE.
/**
* Вычисляет сумму двух чисел.
*
* @param int $a Первое слагаемое
* @param int $b Второе слагаемое
* @return int Сумма
*/
function sum(int $a, int $b): int {
return $a + $b;
}
Цель - повысить читаемость и обеспечить автодокументирование. Подходит для любого публичного API.
Частая проблема
Несоответствие аннотаций реальным типам. Например, указан @param string, а в коде ожидается int. Это вводит в заблуждение. Нужно синхронизировать комментарии с кодом.
Как закомментировать большой блок кода, если внутри уже есть комментарии?
Использование многострочных комментариев невозможно, если блок уже содержит подобные комментарии. Простой выход - обернуть код в конструкцию if (false) { ... }.
if (false) {
// здесь может быть любой код, включая // и /* */
$x = 1;
/* другой комментарий */
}
Такой блок никогда не выполняется. Подходит для временного отключения участков кода. Недостаток - код остаётся в файле, может сбивать с толку.
Возможные проблемы
Внутри блока не должно быть конструкций break или continue вне цикла - они вызовут ошибку. Также легко забыть убрать такой блок перед выкладкой.
Как помечать временные отладочные комментарии и незавершённые задачи?
В коде часто оставляют метки TODO, FIXME, XXX. Они выделяются в IDE и помогают быстро находить места, требующие доработки.
// TODO: добавить проверку ввода
$value = $_POST['input'];
// FIXME: неправильно обрабатывается случай отрицательных чисел
if ($value < 0) { ... }
Метки удобны для организации работы. Главное - регулярно просматривать и удалять их, иначе они засоряют код.
Какие ещё стили комментариев существуют и когда их применять?
Помимо // PHP поддерживает стиль Perl (#). Разницы в выполнении нет, но в сообществе принято использовать //. Также можно использовать пустые многострочные комментарии для визуального разделения блоков. Для документирования всегда выбирайте PHPDoc.
# Это комментарий в стиле Perl
echo 'Hello';
Типичные ошибки
Забытые закрывающие */, комментарии внутри строк (они не работают), а также попытка закомментировать блок, содержащий теги <?php - это не вызовет ошибку, но может запутать. Избегайте комментариев, поясняющих очевидное.
Примеры расширенного использования комментариев
Пример 1: Полный PHPDoc для класса с методами
Демонстрируется использование тегов @package, @author, @deprecated, @see, @throws.
/**
* Класс для работы с пользователями.
*
* @package App\Models
* @author Ivan Ivanov
* @version 1.0
* @see UserController
*/
class User {
/** @var int Идентификатор пользователя */
public int $id;
/**
* Получает имя пользователя.
*
* @return string Имя пользователя
* @throws \RuntimeException Если пользователь не найден
*/
public function getName(): string {
// реализация
}
/**
* Устанавливает email (устаревший метод).
*
* @deprecated 2.0 Используйте setContact()
* @see setContact()
* @param string $email
* @return void
*/
public function setEmail(string $email): void {
// ...
}
}
Такой комментарий позволяет IDE показывать подсказки, а инструменты вроде phpDocumentor создают документацию. @deprecated предупреждает о замене метода.
Пример 2: Комментарий, описывающий алгоритм
Используется для сложной логики, чтобы другие разработчики понимали шаги.
/**
* Бинарный поиск в отсортированном массиве.
*
* Алгоритм:
* 1. Установить левую границу 0, правую - длина массива - 1.
* 2. Пока левая <= правая:
* - Вычислить середину.
* - Если элемент в середине равен искомому, вернуть индекс.
* - Если элемент меньше, сдвинуть левую границу вправо.
* - Иначе сдвинуть правую границу влево.
* 3. Если не найдено, вернуть -1.
*
* @param array $arr Отсортированный массив
* @param mixed $needle Искомое значение
* @return int Индекс элемента или -1
*/
function binarySearch(array $arr, $needle): int {
$left = 0;
$right = count($arr) - 1;
while ($left <= $right) {
$mid = floor(($left + $right) / 2);
if ($arr[$mid] === $needle) {
return $mid;
}
if ($arr[$mid] < $needle) {
$left = $mid + 1;
} else {
$right = $mid - 1;
}
}
return -1;
}
Результат выполнения: при входных данных binarySearch([1,3,5,7,9], 5) вернёт 2. Комментарий помогает быстро вникнуть в алгоритм.
2
Пример 3: Ошибка вложенных многострочных комментариев и её решение
Показана ситуация, когда вложение комментариев приводит к синтаксической ошибке, и способ обойти её.
/*
echo 'Внешний';
/* echo 'Внутренний'; */
echo 'Ещё';
*/
Интерпретатор видит закрывающий */ после 'Внутренний' и считает внешний комментарий завершённым. Затем встречает */ без открывающего - ошибка:
Parse error: syntax error, unexpected end of file ...
Вместо вложенных комментариев используйте if (false) { ... }:
if (false) {
echo 'Внешний';
/* echo 'Внутренний'; */
echo 'Ещё';
}
Такой блок не вызовет ошибку, а код внутри не выполнится.
Пример 4: Комментарии для отладки с var_dump
Временное добавление отладочного вывода с последующим комментированием.
$result = someFunction();
// var_dump($result); // debug
echo $result;
Когда отладка завершена, строка с var_dump остаётся закомментированной. Её можно удалить позже. Чтобы не забыть, используют метки TODO.
Результат: если расскомментировать - покажет содержимое $result.
(при расскомментировании) string(4) "test"
Пример 5: Использование маркеров TODO в реальном проекте
Маркеры помогают структурировать доработки. Пример из реального кода:
// TODO: рефакторинг - вынести логику в отдельный класс
function processData(array $data) {
// FIXME: возможна утечка памяти при больших объёмах
foreach ($data as $item) {
// ...
}
}
Такие комментарии не влияют на выполнение, но служат напоминанием. Перед выкладкой в продакшен их целесообразно удалить или превратить в задачи в трекере.
Пример 6: Комментарии в стиле Perl (#)
Хотя # работает идентично //, в PHP-сообществе он встречается реже. Пример:
# Это комментарий в стиле Perl
echo 'Hello';
Результат: Hello. В остальном никаких отличий. Выбор стиля - дело вкуса, но лучше придерживаться единообразия в проекте.
Hello