Padrões de Código

Padrões de código são acordos da equipe sobre como o código deve ser escrito:

• Convenções de nomenclatura (camelCase vs snake_case)
• Formatação (tabs vs espaços, posicionamento de chaves)
• Organização do código (estrutura de arquivos, limites de módulos)
• Padrões (como lidar com erros, como estruturar testes)

Os padrões permitem a propriedade coletiva. Quando o código tem a mesma aparência em todos os lugares, qualquer pessoa pode ler qualquer código. Não há "tradução" entre o estilo do Bob e o estilo da Alice.

Os padrões também reduzem o atrito na revisão de código. Em vez de debater formatação, você discute lógica e design. As discussões triviais desaparecem.

Sem padrões: Cada arquivo parece diferente. Mover-se entre módulos requer mudança de contexto mental. A revisão de código se torna uma guerra de estilos.

Com padrões: A base de código parece unificada. Ler código desconhecido é mais fácil. As revisões focam no que importa.

Nem todas as convenções são iguais. Distinga entre:

Padrões semânticos: Afetam o comportamento ou a manutenibilidade do código

• Padrões de tratamento de erros
• Convenções de logging
• Estrutura de testes
• Padrões de design de API

Padrões estilísticos: Afetam apenas a aparência

• Formatação (indentação, comprimento de linha)
• Nomenclatura (camelCase vs snake_case)
• Posicionamento de chaves

Padrões semânticos merecem discussão. Como a equipe lida com erros é uma decisão significativa com consequências reais.

Padrões estilísticos devem ser automatizados. Use Prettier, Black, gofmt—ferramentas que formatam código automaticamente. Não desperdice tempo humano com tabs vs espaços.

O objetivo é remover atrito, não alcançar algum ideal platônico de estilo de código.

Ferramentas modernas podem aplicar a maioria dos padrões automaticamente:

Formatadores: Prettier (JavaScript), Black (Python), gofmt (Go), rustfmt (Rust)

• Executam ao salvar ou como um hook de pré-commit
• Eliminam completamente discussões sobre formatação

Linters: ESLint, Pylint, Clippy, RuboCop

• Detectam violações de estilo e possíveis bugs
• Configuráveis de acordo com as preferências da equipe
• Executam no CI para evitar que código não conforme seja mesclado

Verificadores de tipo: TypeScript, mypy, Flow

• Aplicam consistência de tipos
• Detectam erros antes da execução

Hooks de pré-commit: Husky, pre-commit

• Executam verificações antes do código ser commitado
• Detectam problemas antes de entrarem no repositório

Configure uma vez, aplique para sempre. Não confie na disciplina humana—automatize.

Os padrões podem desencadear opiniões fortes. Evite debates intermináveis:

Comece com convenções existentes. Se a linguagem ou framework tem estilo padrão (Go, Rust), apenas use-o. Não reinvente.

Use padrões da indústria. Configurações populares de linter/formatador (Airbnb ESLint, guia de estilo do Google) são testadas em batalha.

Decida rapidamente, ajuste depois. Escolha algo razoável. Se provar ser problemático, mude. Não bloqueie o progresso esperando pelo padrão perfeito.

Torne democrático mas decisivo. Deixe a equipe votar em questões controversas. A maioria vence. A minoria aceita a decisão.

Lembre-se do objetivo. Os padrões existem para reduzir o atrito, não para expressar preferências. Se uma discussão está demorando muito, qualquer escolha razoável está boa.

Os padrões devem ser documentados—mas mantenha-os vivos:

O que documentar:

• Padrões semânticos (como lidar com erros, padrões de teste)
• Justificativa para escolhas não óbvias (por que escolhemos X em vez de Y)
• Exceções e quando quebrar regras
• Como propor mudanças

Onde documentar:

• Arquivo README ou CONTRIBUTING no repositório
• Wiki ou espaço de documentação da equipe
• Comentários na configuração do linter/formatador

Mantenha atualizado. Documentação desatualizada é pior do que nenhuma documentação. Quando você mudar um padrão, atualize os documentos.

Torne fácil de encontrar. Novos membros da equipe devem encontrar os padrões facilmente. Não os enterre em um labirinto de wiki.

A melhor documentação é o próprio código. Se seus padrões são aplicados automaticamente, o código demonstra o que é aceitável.