Boas práticas

Checklist do dia-a-dia

Cola isso na parede (ou na memória):

✅ git pull sempre ANTES de começar a trabalhar ✅ 1 tarefa Jira = 1 branch = 1 PR (pequeno e focado) ✅ Commit message descritiva (o porquê, não só o quê) ✅ Nunca commite credenciais — .env + .gitignore ✅ Nunca push direto no main — sempre via PR ✅ PR < 200 linhas sempre que possível

Credenciais — a regra inegociável

Credencial (API key, senha, token, secret) NUNCA entra no Git. Motivo: Git guarda histórico. Mesmo se você deletar depois, fica no histórico pra sempre.

Como evitar

Cria arquivo .env na raiz do teu sub-projeto:
```
API_KEY=abc123
DATABASE_URL=...
```
Adiciona .env no .gitignore:
Terminal window
```
echo ".env" >> .gitignore
```
Valida que foi ignorado:
.env
```
git check-ignore .env
```
Antes de commit, sempre olha git status — .env não pode aparecer.

Se vazou

Se uma credencial foi commitada e empurrada:

Roda a credencial imediatamente (nova API key, invalida a antiga)
Avisa o Fred
Limpeza do histórico é trabalho separado (não urgente, já que a chave foi rodada)

Tamanho do PR

PR bom é PR que revisa em 15 minutos ou menos.

Linhas	Dificuldade de revisar	Ação
< 50	trivial	merge rápido
50-200	fácil	revisão de manhã
200-500	média	revisão mais demorada
500-1000	difícil	avisa Fred antes
> 1000	impossível	quebra em sub-PRs

Como quebrar PR grande

Estrutura primeiro: primeiro PR cria só as pastas, README, CLAUDE.md. Vazias, sem código.
Funcionalidade por vez: segundo PR adiciona a função A. Terceiro adiciona função B. Etc.
Refactor separado de feature: nunca misture mudança estrutural com mudança de comportamento.

Commit frequente

Commit é de graça. Faça muitos.

❌ Mal: 8h de trabalho, 1 commit gigante "feature X".

✅ Bem: 8h de trabalho, 10 commits pequenos:

setup do arquivo base
adiciona função parseInput
adiciona função validate
tratamento de erro na validate
adiciona teste pra parseInput
refactor parseInput pra usar regex
fix edge case quando input é vazio
adiciona docstring
integra parseInput + validate no endpoint
testa endpoint end-to-end

Por quê? Se algo quebra no 10º commit, você git bisect e acha qual commit específico introduziu o bug. Com 1 commit gigante, tem que abrir linha por linha.

Código morto

Se apagou um uso de variável/função/import, apague também a declaração. Não deixa _var com prefixo de “não usado” — isso vira ruído no repo.

Mesma coisa pra comentários tipo // removed X - kept for backwards compat. Se você tá com certeza que não usa, apaga inteiro. Git guarda o histórico caso precise voltar.

Comments em código

Default: não escreva comments.

Escreve só quando:

Explica o porquê, não o o quê
Documenta uma restrição escondida (ex: “essa API só aceita 5 req/s”)
Alerta pro próximo dev sobre um edge case não-óbvio

❌ Não escreva:

# incrementa x por 1
x += 1

✅ Escreva:

# Counter precisa ser idempotente: a API reprocessa requests em retry.
x += 1 if not already_counted else 0

→ Quando me avisar — importante!