Código limpo

O que torna um nome bom

Revela intenção sem olhar a implementação, não engana, é buscável e consistente. Código é lido muito mais do que escrito — nome ruim custa toda leitura.

'Função faz uma coisa' — o que isso quer dizer

Não dá pra nomear sem 'e'; mistura níveis de abstração; tem seções comentadas; teste exige muitos setups. Uma coisa = um nível de abstração coerente, não X linhas.

Comentário bom x comentário que é desculpa

Bom: explica o 'porquê' não óbvio, avisa consequência, dá contexto externo. Ruim: repete o código, compensa um nome ruim, ou está desatualizado. Prefira código claro a comentário.

DRY tem limite: acoplamento por coincidência

DRY é sobre conhecimento único, não código parecido. Abstrair cedo amarra usos que divergem depois — 'duplicação é mais barata que a abstração errada'. Espere o terceiro caso.

Regra do escoteiro e refatoração incremental

Melhore um pouco todo arquivo que tocar (nome, função extraída, código morto). Risco baixo, entra com trabalho já revisado, melhora onde há atividade. Big refactor é adiado e incha.

Cenário: a função com três parâmetros booleanos

Booleanos posicionais são ilegíveis e trocáveis, e sinalizam múltiplos comportamentos. Troque por objeto de opções nomeadas, funções separadas, ou um enum de modo.

Guard clauses x aninhamento profundo de if

Guards tratam saídas no topo e retornam, deixando o caminho feliz plano e legível. O if aninhado empurra o corpo pra dentro e afasta o erro da condição que o causou.

Números e strings mágicos

O literal não diz o que significa nem por quê. Extraia pra constante com nome do CONCEITO (não `const TRES`). Não extraia o que já é óbvio (`array[0]`, `i+1`); `24*60*60*1000` já ajuda sem constante.

Efeito colateral escondido: a função que mente sobre o que faz

O nome `get` promete leitura pura mas escreve — chamador não sabe, testes e loops disparam efeitos surpresa. Separe comando de consulta (CQS); auditoria vira responsabilidade explícita, não efeito escondido.

O que priorizar num code review

Correção → teste → segurança/dados → design/fronteiras/reuso → legibilidade → nits (que o linter deveria pegar). Classifique os comentários (bloqueia/sugestão), aprove com nits pequenos, PRs pequenos.

TODO, FIXME e comentários que apodrecem

TODO solto = lembrete sem dono que vira ruído. Use `TODO(#issue): contexto`, transforme trabalho real em ticket, deixe o CI barrar FIXME sem issue, e apague os obsoletos.

Cenário: a abstração de plugin que ninguém usou

Peça um segundo caso de uso concreto e datado. Sem ele: implemente o caso único simples e bem fatorado; generalize quando o segundo chegar (a abstração sem exemplo real costuma sair errada). YAGNI + regra do terceiro caso.

Por que discutir estilo em review é desperdício

Discussão de estilo rouba atenção da correção/design e gera atrito de gosto. Automatize: formatter no save + pré-commit, linter pras regras que pegam bug, CI barra o que está torto. A ferramenta decide por todos.