Документация в PHP: как писать код, который не стыдно показать

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

Ваш код говорит громче слов? Нет, если вы пишете на PHP

Представьте: вы открываете старый PHP-проект, который писали полгода назад. Вы смотрите на функцию processData() и понимаете... ровным счётом ничего. Что за данные? Откуда они берутся? Почему метод называется doMagic()? Знакомо? Если да — эта статья для вас.

Хорошая документация в PHP — это не просто "вежливость" по отношению к коллегам. Это ваш страховой полис от головной боли, ускорение онбординга новых разработчиков и, в конечном счёте, качество вашего продукта. В этой статье мы разберём лучшие практики документирования PHP-кода, которые превратят ваш хаотичный код в стройную, понятную систему.

Почему документация в PHP — это не "лишняя работа"?

Многие разработчики считают, что "хороший код говорит сам за себя". Это правда лишь отчасти. Хороший код объясняет как он работает, но он редко объясняет зачем и почему именно так. Документация закрывает эти пробелы. Она отвечает на вопросы:

Какие входные данные ожидает функция?
Что она возвращает в случае ошибки?
Почему было принято такое архитектурное решение?
Какие побочные эффекты есть у метода?

Без ответов на эти вопросы ваш код — это чёрный ящик. А чёрные ящики боятся трогать даже опытные разработчики.

PHPDoc: Ваш главный инструмент

Стандарт де-факто для документирования PHP-кода — это PHPDoc. Это специальный формат комментариев, который начинается с /** и заканчивается */. Он поддерживается всеми современными IDE (PhpStorm, VS Code) и инструментами генерации документации, такими как phpDocumentor или Doxygen.

Базовый синтаксис PHPDoc включает в себя:

@param — описание параметров метода или функции
@return — тип и описание возвращаемого значения
@throws — какие исключения может выбрасывать метод
@var — тип свойства класса
@see — ссылка на связанный метод или класс
@deprecated — пометка, что функционал устарел

Пример хорошего PHPDoc-блока

<?php

/**
 * Рассчитывает финальную стоимость заказа с учётом скидки и налогов.
 *
 * Этот метод применяет прогрессивную шкалу скидок в зависимости от суммы заказа.
 * Если сумма превышает 10 000 рублей, применяется максимальная скидка 15%.
 *
 * @param float $basePrice Базовая стоимость заказа без скидок (в рублях).
 * @param float $taxRate   Ставка налога, например, 0.20 для 20%.
 * @param string $currency Валюта для форматирования результата (по умолчанию 'RUB').
 *
 * @return string Отформатированная строка с итоговой стоимостью, например "12 500.00 ₽".
 *
 * @throws \InvalidArgumentException Если базовая стоимость отрицательная.
 * @throws \RuntimeException         Если не удалось получить курс валюты.
 *
 * @see \PriceCalculator::applyDiscounts() Для деталей расчёта скидок.
 */
public function calculateFinalPrice(float $basePrice, float $taxRate, string $currency = 'RUB'): string
{
    if ($basePrice < 0) {
        throw new \InvalidArgumentException('Базовая стоимость не может быть отрицательной.');
    }
    // ... логика расчёта
}

Обратите внимание: мы не просто перечислили типы, но и объяснили контекст (прогрессивная шкала), формат (отформатированная строка) и граничные условия (исключения). Это и есть качественная документация.

Лучшие практики: от простого к сложному

1. Документируйте публичный API, не трогайте private

Не нужно писать PHPDoc для каждого приватного геттера или сеттера. IDE и так видит тип. Сосредоточьтесь на публичных методах и интерфейсах — это то, с чем взаимодействуют другие части системы. Для приватных методов достаточно краткого комментария, если логика нетривиальна.

2. Используйте строгую типизацию (PHP 7.4+)

Если вы используете declare(strict_types=1); и указываете типы аргументов и возврата, то PHPDoc-блок может быть короче. Например:

<?php

/**
 * Получает пользователя по ID.
 *
 * @param int $id Идентификатор пользователя.
 *
 * @return User|null Объект пользователя или null, если не найден.
 */
public function findUserById(int $id): ?User
{
    // ...
}

Типы int и ?User уже указаны в сигнатуре — дублировать их в PHPDoc не обязательно, но для совместимости со старыми инструментами это часто делают.

3. Описывайте побочные эффекты

Самый коварный код — тот, который что-то делает "под капотом". Например, метод save() может не только сохранять данные, но и отправлять email или писать в лог. Обязательно указывайте это в документации с помощью тега @sideeffect или просто в описании.

/**
 * Сохраняет заказ в базу данных.
 *
 * ВНИМАНИЕ: Этот метод также отправляет уведомление менеджеру по email
 * и обновляет кэш отчётов.
 *
 * @param Order $order Объект заказа.
 *
 * @return bool True в случае успеха.
 */
public function save(Order $order): bool
{
    // ...
}

4. Документируйте исключения (@throws)

В PHP исключения — это часть контракта метода. Если ваш метод может выбросить PDOException или ValidationException, обязательно укажите это. Это поможет разработчикам правильно обрабатывать ошибки.

5. Используйте @see и @link для навигации

Большие проекты — это сети взаимосвязей. Используйте @see, чтобы указать на связанные классы или методы, и @link для внешних ресурсов (например, ссылка на документацию API).