Documentação em PHP: como escrever código que se explica sozinho

Por que seu projeto PHP está condenado sem documentação?

Imagine: você abre um projeto que escreveu há seis meses. Pilhas de arquivos, nomes de variáveis estranhos e, o pior de tudo, nenhum comentário. Parece familiar? Agora imagine que esse projeto precisa ser passado para um novato na equipe ou, ainda pior, para o cliente. Sem documentação, isso vira um jogo de "Adivinhe o que este método faz".

Na comunidade PHP, existe uma regra não escrita: um bom código é documentado de forma que qualquer desenvolvedor nível Júnior consiga entendê-lo. E não se trata de escrever romances nos comentários. Trata-se de um sistema que economiza horas da sua vida.

Neste artigo, vamos explorar as melhores práticas de documentação para projetos PHP. Você vai aprender como fazer seu código falar por si só, e a documentação se tornar uma aliada, não uma dor de cabeça.

PHPDoc: sua principal ferramenta

Vamos começar pelo básico. PHPDoc é o padrão de anotação de código em PHP. Ele é compreendido pela maioria das IDEs (PhpStorm, VS Code) e ferramentas como phpDocumentor. Se você ainda não usa PHPDoc, está perdendo tempo decifrando seu próprio código.

Como formatar blocos PHPDoc corretamente

O modelo básico para uma função ou método é assim:

/**\n * Descrição resumida do que a função faz.\n *\n * Descrição detalhada (opcional), se precisar explicar uma lógica complexa.\n *\n * @param string $name Nome do usuário.\n * @param int $age Idade do usuário (opcional).\n * @return string Mensagem de boas-vindas.\n *\n * @throws \\InvalidArgumentException Se o nome estiver vazio.\n */\nfunction greetUser(string $name, int $age = 0): string\n{\n    if (empty($name)) {\n        throw new \\InvalidArgumentException('O nome não pode estar vazio');\n    }\n    \n    $greeting = "Olá, {$name}!";\n    if ($age > 0) {\n        $greeting .= " Você tem {$age} anos.";\n    }\n    \n    return $greeting;\n}

Pontos-chave:

\n
• @param — descreve o tipo e a finalidade de cada argumento.
\n
• @return — indica o tipo do valor retornado e seu significado.
\n
• @throws — lista as exceções que o método pode lançar. Isso evita surpresas em tempo de execução.
\n

Anotações para propriedades de classes

As propriedades também precisam ser documentadas, especialmente se tiverem tipos complexos:

class UserService\n{\n    /**\n     * Repositório de usuários para trabalhar com o banco de dados.\n     *\n     * @var UserRepositoryInterface\n     */\n    private UserRepositoryInterface $userRepository;\n\n    /**\n     * Cache para armazenar resultados de busca.\n     *\n     * @var CacheInterface|null\n     */\n    private ?CacheInterface $cache = null;\n}

Observe: usamos @var para indicar o tipo. Mesmo com tipagem estrita (PHP 7.4+), a anotação ajuda a IDE e analisadores estáticos.

Erros comuns no PHPDoc (e como evitá-los)

Até desenvolvedores experientes cometem deslizes. Veja os mais frequentes:

\n
• Blocos vazios: /** */ antes de uma função é lixo inútil. Ou escreva algo relevante, ou remova.
\n
• Informação desatualizada: mudou a assinatura do método, mas esqueceu de atualizar o PHPDoc. Resultado: desinformação. Sempre sincronize a documentação com o código.
\n
• Redundância: não escreva @return string se já está claro que a função retorna uma string. O PHPDoc deve explicar o significado, não duplicar o tipo.
\n

README: a cara do seu projeto

PHPDoc é a documentação interna para desenvolvedores. Já o README.md é o que todos veem: de colegas a visitantes casuais do GitHub. Um bom README responde a três perguntas:

\n
1. O que é isso? — uma descrição resumida do projeto.
\n
2. Como instalar? — instruções claras de configuração.
\n
3. Como usar? — exemplos práticos de uso.
\n

Invista tempo no seu README. Ele é o cartão de visitas do seu código.