Boas práticas de desenvolvimento¶

Esta seção apresenta recomendações para que os times mantenham um padrão mínimo de qualidade no código, independente da linguagem, framework ou arquitetura utilizada.

As práticas aqui descritas não substituem as diretrizes específicas de cada projeto, mas servem como base comum para todos os colaboradores.

Organização do código-fonte¶

Manter a estrutura de diretórios alinhada com a arquitetura definida para o sistema.
Nomear arquivos, classes, funções e variáveis de forma descritiva e consistente.
Evitar funções muito longas; extrair responsabilidades em funções menores e reutilizáveis.
Centralizar constantes e configurações em locais apropriados, evitando valores mágicos espalhados pelo código.

Padronização e estilo¶

Seguir os guias de estilo recomendados para cada linguagem (por exemplo, PEP 8 para Python, eslint/prettier para JavaScript/TypeScript).
Utilizar ferramentas de formatação automática e linters integrados ao fluxo de desenvolvimento.
Manter um padrão consistente de nomenclatura, indentação e organização de imports.

Tratamento de erros e logging¶

Tratar erros de forma explícita, evitando capturas genéricas que escondam problemas.
Registrar logs em pontos relevantes do fluxo, com nível adequado (info, warning, error).
Evitar expor dados sensíveis (como senhas, tokens ou informações de clientes) em logs.

Testes automatizados¶

Priorizar testes unitários para regras de negócio críticas.
Criar testes de integração para fluxos principais e integrações externas.
Incluir testes em novos desenvolvimentos e ao corrigir defeitos, sempre que possível.

Revisão de código¶

Utilizar pull requests para todas as alterações que impactam o código de produção.
Concentrar a revisão em clareza, legibilidade, complexidade e aderência aos padrões definidos.
Discutir melhorias de forma respeitosa e objetiva, registrando decisões arquiteturais relevantes.

Documentação¶

Atualizar a documentação técnica quando forem introduzidas mudanças significativas na arquitetura ou no comportamento do sistema.
Manter exemplos de uso atualizados em README, coleções de API e demais artefatos de apoio.
Registrar decisões técnicas importantes (trade-offs, alternativas avaliadas e justificativas).

Segurança¶

Seguir as diretrizes da seção de segurança em Desenvolvimento para tratamento de credenciais, validação de entrada e comunicação segura.
Nunca versionar segredos em repositórios de código-fonte.
Utilizar mecanismos de configuração seguros (variáveis de ambiente, serviços de segredo, cofres, entre outros).

Essa seção deve evoluir continuamente. Ao identificar boas práticas adotadas com sucesso em projetos, inclua-as aqui para que sejam compartilhadas com toda a organização.