Código limpo em PHP: guia essencial para desenvolvedores profissionais

Introdução: por que "código limpo" não é sobre perfeccionismo, mas sobre dinheiro e sanidade mental

Imagine que você entra em um projeto PHP antigo, escrito há um ano. Você abre o arquivo index.php e encontra uma mistura de HTML, consultas SQL, echo e funções com nomes como f1(). Familiar? Se sim, você é ou um iniciante começando sua jornada, ou um desenvolvedor experiente que herdou um projeto "legado".

Código limpo em PHP não é uma questão de moda ou um capricho do tech lead. É uma ferramenta que economiza horas, nervos e dinheiro. Neste artigo, vamos explorar como transformar seu código PHP de um "rascunho bagunçado" em uma "versão final" que agradará você e seus colegas. Falaremos sobre os padrões PSR, princípios SOLID, nomenclatura correta e daremos exemplos reais. Vamos nessa!

1. Filosofia do código limpo: princípios fundamentais

Antes de mergulharmos na sintaxe, vamos alinhar as regras do jogo. Código limpo é aquele que:

\n
• É compreensível sem comentários (embora comentários às vezes sejam necessários).
\n
• É fácil de testar.
\n
• Não tem medo de refatoração.
\n
• Segue um estilo consistente em todo o projeto.
\n

Robert Martin (Uncle Bob) disse em seu livro "Código Limpo": "A única maneira de ir rápido é ir bem". Se você escreve rápido e de forma bagunçada, em um mês gastará 10 vezes mais tempo depurando. Vamos aprender com os erros dos outros, não com os nossos.

2. Padrões PSR: seu primeiro passo para a organização

No mundo PHP, existem os PSR (PHP Standards Recommendations) — recomendações adotadas pela comunidade. Se você não os utiliza, no mínimo está dificultando a vida de si mesmo e dos colegas que lerão seu código.

2.1 PSR-1 e PSR-12: Estilo básico de codificação

O PSR-1 define regras gerais, e o PSR-12 é o estilo estendido. Aqui estão alguns pontos-chave:

\n
• Arquivos devem usar apenas <?php ou <?=.
\n
• Codificação dos arquivos: UTF-8 sem BOM.
\n
• Nomes de classes devem estar em StudlyCaps (exemplo: UserController).
\n
• Nomes de métodos e propriedades em camelCase (exemplo: getUserName()).
\n
• Indentação: 4 espaços (não use tabulação!).
\n

Exemplo de código ruim:

<?\nclass user_controller {\n\tfunction Get_User_Name($id) {\n\t\t$name = Db::query("SELECT name FROM users WHERE id=$id");\n\t\treturn $name;\n\t}\n}\n

Exemplo de código bom (PSR-12):

<?php\n\ndeclare(strict_types=1);\n\nnamespace App\\Controllers;\n\nuse App\\Models\\User;\n\nclass UserController\n{\n    public function getUserName(int $id): ?string\n    {\n        $user = User::find($id);\n        return $user ? $user->getName() : null;\n    }\n}\n

Percebe a diferença? A segunda versão se lê como um livro: fica claro o que o método faz, quais tipos de dados ele recebe e retorna.

2.2 PSR-4: Carregamento automático de classes

Esqueça o require_once em cada arquivo. Use o Composer e o PSR-4. Isso permite carregar classes automaticamente com base nos namespaces. A estrutura de pastas deve corresponder aos namespaces:

src/\n  App/\n    Controllers/\n      UserController.php\n    Models/\n      User.php\n    Services/\n      PaymentService.php\n

No composer.json, isso é configurado com uma linha:

{\n    "autoload": {\n        "psr-4": {\n            "App\\\\": "src/"\n        }\n    }\n}\n

3. Nomenclatura correta: como não chamar uma variável de $a

A nomenclatura representa 50% do sucesso. Um nome de variável ruim pode confundir até um gênio. Vamos analisar erros comuns.

3.1 Evite abreviações (exceto as óbvias)