Clean Code em PHP: princípios e exemplos na prática

Introdução: por que código limpo em PHP não é luxo, mas necessidade

Todo desenvolvedor PHP já enfrentou pelo menos uma vez a situação em que um simples bug em ambiente de produção se transforma em uma caçada de horas ao "diabo nos detalhes". Na maioria das vezes, a causa não está na complexidade da lógica, mas no código sujo: nomes de variáveis sem sentido, funções com 500 linhas, falta de tipos e comentários mentirosos. Clean Code (Código Limpo) não é apenas estética. É uma ferramenta que reduz o custo de manutenção do projeto em 3 a 5 vezes e permite que novos membros da equipe se integrem ao projeto em horas, não em semanas.

Neste artigo, vamos analisar os princípios-chave do Clean Code aplicados ao PHP, apoiados por exemplos reais de antes e depois da refatoração. Você aprenderá a aplicar os padrões PSR, os princípios SOLID e regras simples de nomenclatura para que seu código fale por si só.

1. Nomeação de variáveis, funções e classes: fale a linguagem do negócio

Um nome ruim é o principal inimigo da legibilidade. Se uma variável se chama $a ou $data, toda vez que você lê o código, gasta recursos mentais para decifrá-la. A regra é simples: o nome deve responder à pergunta "O que é isso?" ou "O que faz?"

Exemplo ruim

<?php// O que é $d? Por que $x = 2?$d = new DateTime();$x = 2;$y = $d->modify('+' . $x . ' days');echo $y->format('Y-m-d');?>

Exemplo bom (Clean Code)

<?php$currentDate = new DateTime();$daysToAdd = 2;$futureDate = $currentDate->modify('+' . $daysToAdd . ' days');echo $futureDate->format('Y-m-d');?>

Regras adicionais:

• Classes e interfaces — substantivos: UserRepository, PaymentGatewayInterface.
• Métodos — verbos: getUserById(), sendEmailNotification().
• Variáveis booleanas — prefixos is, has, can: $isActive, $hasPermission.
• Evite abreviações: $cnt → $count, $usr → $user.

2. Funções e métodos: princípio da responsabilidade única (SRP) em ação

Uma função — uma ação. Se você vê uma função com mais de 20–30 linhas, provavelmente ela pode ser dividida. Em PHP, isso é especialmente relevante, pois a falta de tipagem estrita (até o PHP 7.4) provoca "depósitos" de código.

Exemplo ruim: função canivete suíço

<?phpfunction processOrder(array $orderData): array{    // Validação    if (empty($orderData['email'])) {        throw new InvalidArgumentException('Email required');    }    // Salvamento no BD    $pdo = new PDO('mysql:host=localhost;dbname=test', 'root', '');    $stmt = $pdo->prepare('INSERT INTO orders (email, total) VALUES (?, ?)');    $stmt->execute([$orderData['email'], $orderData['total']]);    // Envio de email    mail($orderData['email'], 'Order Confirmed', 'Thank you!');    // Logging    file_put_contents('log.txt', 'Order processed: ' . $orderData['email'] . PHP_EOL, FILE_APPEND);    return ['status' => 'success'];}?>

Exemplo bom: separação de responsabilidades

<?phpclass OrderProcessor{    private OrderValidator $validator;    private OrderRepository $repository;    private MailService $mailer;    private Logger $logger;

    public function __construct(        OrderValidator $validator,        OrderRepository $repository,        MailService $mailer,        Logger $logger    ) {        $this->validator = $validator;        $this->repository = $repository;        $this->mailer = $mailer;        $this->logger = $logger;    }

    public function process(array $orderData): arr