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

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

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

Начать курс

Почему без документации ваш PHP-проект обречен?

Представьте: вы открываете проект, который писали полгода назад. Куча файлов, странные названия переменных, а главное — ни одного комментария. Знакомо? А теперь представьте, что этот проект нужно передать новичку в команде или, что еще хуже, заказчику. Без документации это превращается в квест «Угадай, что делает этот метод».

В PHP-сообществе есть негласное правило: хороший код документирован так, что его может понять любой разработчик уровня Junior. И речь не о том, чтобы писать поэмы в комментариях. Речь о системе, которая экономит часы вашей жизни.

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

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

Начнем с основ. PHPDoc — это стандарт аннотирования кода в PHP. Он понимается большинством IDE (PhpStorm, VS Code) и инструментами вроде phpDocumentor. Если вы еще не используете PHPDoc, вы теряете время на расшифровку собственного кода.

Как правильно оформлять PHPDoc-блоки

Базовый шаблон для функции или метода выглядит так:

/**
 * Краткое описание того, что делает функция.
 *
 * Подробное описание (опционально), если нужно объяснить сложную логику.
 *
 * @param string $name Имя пользователя.
 * @param int $age Возраст пользователя (опционально).
 * @return string Приветственное сообщение.
 *
 * @throws \InvalidArgumentException Если имя пустое.
 */
function greetUser(string $name, int $age = 0): string
{
    if (empty($name)) {
        throw new \InvalidArgumentException('Имя не может быть пустым');
    }
    
    $greeting = "Привет, {$name}!";
    if ($age > 0) {
        $greeting .= " Тебе {$age} лет.";
    }
    
    return $greeting;
}

Ключевые моменты:

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

Аннотации для свойств классов

Свойства тоже нужно документировать. Особенно если они имеют сложные типы:

class UserService
{
    /**
     * Репозиторий пользователей для работы с БД.
     *
     * @var UserRepositoryInterface
     */
    private UserRepositoryInterface $userRepository;

    /**
     * Кэш для хранения результатов поиска.
     *
     * @var CacheInterface|null
     */
    private ?CacheInterface $cache = null;
}

Обратите внимание: мы используем @var для указания типа. Даже если у вас строгая типизация (PHP 7.4+), аннотация помогает IDE и статическим анализаторам.

Типичные ошибки в PHPDoc (и как их избежать)

Даже опытные разработчики иногда допускают ляпы. Вот самые частые:

Пустые блоки: /** */ перед функцией — это бесполезный мусор. Либо пишите осмысленно, либо удаляйте.
Устаревшая информация: изменили сигнатуру метода, но забыли обновить PHPDoc. Результат — дезинформация. Всегда синхронизируйте документацию с кодом.
Избыточность: не пишите @return string, если и так видно, что функция возвращает строку. PHPDoc должен объяснять смысл, а не дублировать тип.

README: лицо вашего проекта

PHPDoc — это внутренняя документация для разработчиков. А вот README.md — это то, что видят все: от коллег до случайных посетителей GitHub. Хороший README отвечает на три вопроса:

Что это? — краткое описание проекта.
Как это установить? — четкая инструкция.
Как этим пользоваться? — примеры кода.

Шаблон README для PHP-проекта

# MyAwesomePHPProject

Простая библиотека для работы с REST API.

## Установка

```bash
composer require vendor/my-awesome-project
```

## Использование

```php
$client = new ApiClient('https://api.example.com');
$response = $client->get('/users');
```

## Документация

Полная документация доступна в [Wiki](link-to-wiki).

## Тестирование

```bash
vendor/bin/phpunit
```

Совет: добавьте бейджи (CI/CD, версия PHP, лицензия). Они делают README профессиональным и показывают, что проект поддерживается.

Автоматизация: генерируем документацию правильно

Ручное поддержание документации — это ад. К счастью, есть инструменты, которые делают это за вас.

phpDocumentor

Классический инструмент для генерации HTML-документации из PHPDoc-блоков. Пример запуска:

phpdoc -d ./src -t ./docs

Он создаст папку docs с красивой навигацией по классам и методам. Минус: требует настройки и не всегда дружит с современными фичами PHP (например, атрибутами).

Sami (устарел, но жив)

Легковесная альтернатива. Работает быстрее, но поддержка прекращена. Если проект старый — можно использовать.

Doctum (современная замена Sami)

Активно развивается, поддерживает PHP 8.x и атрибуты. Пример конфига:

# doctum.php
return new Doctum\Doctum('/path/to/src', [
    'title' => 'My API',
    'build_dir' => '/path/to/docs',
    'cache_dir' => '/tmp/cache',
]);

Документирование API: Swagger и OpenAPI

Если ваш PHP-проект — это REST API (например, на Laravel или Symfony), то PHPDoc уже не хватит. Нужен Swagger/OpenAPI. Это стандарт для описания эндпоинтов.

Пример аннотации для PHP (с использованием библиотеки zircote/swagger-php):

/**
 * @OA\Get(
 *     path="/api/users/{id}",
 *     @OA\Parameter(
 *         name="id",
 *         in="path",
 *         required=true,
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(
 *         response="200",
 *         description="Информация о пользователе",
 *         @OA\JsonContent(ref="#/components/schemas/User")
 *     )
 * )
 */
public function show(int $id): JsonResponse
{
    // ...
}

Генератор создаст swagger.json, который можно загрузить в Swagger UI или Postman. Это must-have для любого публичного API.