Pular para o conteúdo principal

Code style

Regras de código não-negociáveis. Servem pra todos os repos. Lint e Prettier rodam no pre-commit (Husky) e no CI — você não precisa lembrar dessas regras o tempo todo, a tooling cobra. Mas conhecer agora economiza review depois.

Funções e arquivos​

  • Funções: 4-20 linhas. Se passou, separa em outra função.
  • Arquivos: sob 500 linhas. Se passou, separa por responsabilidade.
  • Uma coisa por função, uma responsabilidade por módulo (SRP).
  • Nomes: específicos e únicos. Evita data, handler, Manager. Prefere nomes que retornem menos de 5 grep hits no codebase.

Tipagem​

  • Tipos explícitos. No TypeScript: nada de any, nada de Dict, nada de função sem tipo.
  • Early returns sobre nested ifs.
  • Máximo 2 níveis de indentação em cada função.
  • Mensagens de exceção precisam incluir o valor que veio errado E a shape esperada.

Sem duplicação​

Sem código duplicado. Extrai pra função/módulo. Mas três linhas parecidas não é duplicação — é coincidência. Não cria abstração prematura.

Comentários​

  • Não escreve comentário óbvio. // incrementa contador em cima de i++ é ruído.
  • Escreve o WHY, não o WHAT. Por que essa linha existe, não o que ela faz.
  • Docstrings em funções públicas: intenção + 1 exemplo de uso.
  • Se uma linha existe por causa de um bug específico ou constraint upstream, referencia o issue/PR no comentário.
  • Não strippa comentários alheios em refactor — eles carregam intenção e história.

Testes​

  • Todo novo function ganha teste.
  • Todo bug fix ganha regression test (escreve teste que reproduz o bug antes de corrigir).
  • F.I.R.S.T.: Fast, Independent, Repeatable, Self-validating, Timely.
  • Mock I/O externo (API, DB, filesystem) com classes fake nomeadas — não stub inline.

Dependências​

  • Injeta dependências via constructor/parâmetro, não via global/import direto.
  • Wrap libs de terceiros atrás de uma interface própria do projeto. Isso isola você de mudanças upstream.

Estrutura de projeto​

  • Segue convenção do framework (Vite/React/Express/etc.).
  • Módulos pequenos focados > god files.
  • Paths previsíveis: controller/model/view, src/lib/test.

Formatação​

  • Usa o formatador default da linguagem (Prettier no caso).
  • Não discute estilo. O formatador resolve.

Logging​

  • Logs estruturados (JSON) em backend pra debugging/observability.
  • Texto plano só pra saída de CLI voltada pro usuário.
  • Nunca loga PII (CPF, e-mail, dados de saúde).

Conventional Commits​

<tipo>(<escopo>): <descrição>

Tipos: feat, fix, docs, style, refactor, perf, test, chore.

Exemplos:

feat: adicionar filtro de alunos no dashboard
fix: corrigir cálculo de tempo de treino
docs: atualizar README com instruções de deploy

Husky valida na hora do commit. Se o commit não passar, o Husky bloqueia.

Quando duvidar​

Se uma regra dessa lista entrar em conflito com o que você precisa fazer pra resolver o problema real do usuário, fala no PR ou no grupo. As regras existem pra ajudar — não pra atrapalhar. Mas a discussão precisa ser explícita, não silenciosa.