Пишем код по правилам: Code Style и конвенции PHP для команды

Работа в команде: code style и конвенции для PHP

Представьте, что вы заходите в чужой проект на PHP. Открываете файл, а там — табуляция перемешана с пробелами, переменные названы как попало, а фигурные скобки стоят где угодно, но только не там, где привыкли вы. Знакомо? А теперь представьте, что таких файлов — сотни, и каждый писал другой разработчик. Кошмар для code review и поддержки кода.

В этой статье мы разберем, почему code style PHP и конвенции кода — это не просто прихоть старшего разработчика, а основа эффективной командной работы. Вы узнаете о стандартах PSR, правилах нейминга, форматирования и получите реальные примеры, которые можно сразу применить в своем проекте.

Почему code style — это важно для команды?

Когда в проекте работает несколько разработчиков, единый стиль кода становится спасением. Вот почему:

• Читаемость. Код, написанный по единым правилам, легко читается любым участником команды. Не нужно гадать, что имел в виду автор.
• Скорость code review. Если код оформлен одинаково, ревьювер сосредотачивается на логике, а не на форматировании.
• Меньше багов. Единые конвенции уменьшают вероятность ошибок, связанных с разными подходами к написанию кода.
• Легкий онбординг. Новый разработчик быстрее вливается в проект, если код предсказуем и структурирован.

По сути, стандарты кодирования PHP — это язык, на котором общается вся команда. Чем он единообразнее, тем меньше недопонимания.

Основные стандарты: PSR и не только

В мире PHP есть несколько ключевых рекомендаций, которые стали де-факто стандартами. Самые важные — PSR-1 и PSR-12 (ранее PSR-2). Их поддерживает PHP-FIG (Framework Interoperability Group).

PSR-1: Базовые правила

PSR-1 описывает самые общие правила: как называть классы, методы, константы и как организовывать файлы.

Основные пункты:

• Файлы должны использовать только <?php или <?= (короткий тег для вывода).
• Кодировка файла — UTF-8 без BOM.
• Имена классов в StudlyCaps (PascalCase).
• Имена методов в camelCase.
• Константы — в верхнем регистре с подчеркиваниями (MAX_VALUE).

Пример правильного кода по PSR-1:

<?php

namespace App\Services;

class UserService
{
    const DEFAULT_ROLE = 'user';

    public function getUserById(int $id): ?User
    {
        // логика
    }

    public function isAdmin(): bool
    {
        // логика
    }
}

PSR-12: Расширенные правила стиля

PSR-12 — это эволюция PSR-2. Он добавляет больше деталей по форматированию.

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

• Отступы — 4 пробела (не табуляция).
• Фигурные скобки открываются на той же строке для классов, методов и управляющих конструкций (K&R стиль).
• После ключевых слов (if, else, while) обязателен пробел.
• Пустая строка после объявления namespace и перед return в методах (опционально).
• Строка не длиннее 120 символов (рекомендуется 80).

Пример правильного форматирования по PSR-12:

<?php

namespace App\Controllers;

use App\Models\User;
use App\Services\AuthService;

class AuthController
{
    private AuthService $authService;

    public function __construct(AuthService $authService)
    {
        $this->authService = $authService;
    }

    public function login(array $credentials): bool
    {
        if (empty($credentials['email']) || empty($credentials['password'])) {
            return false;
        }

        return $this->authService->authenticate($credentials);
    }
}

Конвенции нейминга: как называть переменные, функции и классы

Нейминг — это искусство. Хорошее имя переменной заменяет комментарий. Плохое — вводит в заблуждение.

Переменные и свойства

• Используйте camelCase: $userName, $totalPrice.
• Избегайте сокращений: вместо $usrNm пишите $userName.
• Для boolean переменных используйте префиксы is, has, can: $isActive, $hasPermission.

Функции и методы

• Тоже camelCase: getUser(), calculateTotal().
• Название должно отражать действие: saveUser(), deletePost().
• Избегайте глаголов типа doStuff() или processData() — они ничего не говорят.

Классы и интерфейсы

• Используйте PascalCase: UserRepository, PaymentGateway.
• Интерфейсы часто называют с суффиксом Interface или префиксом I: UserRepositoryInterface или IUserRepository (первый вариант предпочтительнее в PHP-сообществе).
• Абстрактные классы — с префиксом Abstract: AbstractController.

Константы

• Только верхний регистр с подчеркиваниями: MAX_RETRY_COUNT, DEFAULT_LANG.

Плохой пример:

$x = 5;
function get() { ... }
class data { ... }

Хороший пример:

$maxRetries = 5;
function getMaxRetries(): int { ... }
class RetryManager { ... }

Форматирование кода: пробелы, скобки, отступы

Даже такие мелочи, как расположение скобок, могут вызывать споры в команде. Чтобы избежать холиваров, договоритесь о едином стиле.

Отступы

Используйте 4 пробела. Настройте IDE так, чтобы табуляция автоматически заменялась на пробелы. Это обеспечит одинаковый вид кода на любом редакторе.

Фигурные скобки

Открывающая скобка для классов, методов и управляющих конструкций — на той же строке.

Принятый стиль