'Nit: extra blank line on line 42.'
'Nit: linha em branco extra na linha 42.'Aula
Code review C1: depth and tact
Nível: C1
Objetivo
Fazer code review em C1 com profundidade técnica e tato interpessoal: sugerir mudanças estruturais, diferenciar nit de blocker, explicar princípios, e propor alternativas. O foco é review que ensina, sem desmotivar.
Explicação
Code review C1 não é 'aprovar ou reprovar': é colaborar para que o código fique melhor. Quatro movimentos:
1. Diferenciar nit de blocker
Nit é cosmético, não bloqueia o merge. `Nit: extra blank line on line 42.` Blocker é problema real. `Blocker: this query has no index; in production it will scan 10M rows.` C1 marca os dois explicitamente; sem isso, o autor não sabe o que é obrigatório e o que é opcional.
2. Sugerir mudanças estruturais com princípio
Review C1 não diz 'isso está errado'; diz 'isso pode ficar melhor porque princípio X'. `Could we extract this into a helper? Right now it is repeated 5 times, and the principle of DRY suggests a single source of truth.` Review com princípio é review que ensina; review sem princípio é opinião.
3. Propor alternativa, não só crítica
C1 sempre oferece caminho. `What do you think about using a `defaultdict` here? It would remove the explicit `if key not in dict` check.` Crítica sem alternativa é reclamação; com alternativa, é colaboração.
4. Linguagem calibrada por severidade
C1 usa verbos diferentes para severidades diferentes. `Blocker:` (problema sério), `Suggestion:` (vale considerar), `Nit:` (cosmético), `Question:` (preciso entender). A linguagem calibrada deixa o autor saber o que é urgente; sem calibração, tudo vira 'isso está ruim'.
Exemplos
| Inglês | Tradução | Observação |
|---|---|---|
| Nit: extra blank line on line 42. | Nit: linha em branco extra na linha 42. | Nit: cosmético, não bloqueia. |
| Blocker: this query has no index; in production it will scan 10M rows. | Blocker: esta query não tem índice; em produção vai escanear 10 milhões de linhas. | Blocker: problema real, bloqueia o merge. |
| Could we extract this into a helper? Right now it is repeated 5 times, and the principle of DRY suggests a single source of truth. | Podemos extrair isso em um helper? Agora está repetido 5 vezes, e o princípio de DRY sugere uma única fonte de verdade. | Mudança estrutural com princípio. |
| What do you think about using a defaultdict here? It would remove the explicit if key not in dict check. | O que você acha de usar um defaultdict aqui? Removeria a checagem explícita 'if key not in dict'. | Sugestão com alternativa explícita. |
Erros comuns
- Tratar tudo como blocker: o autor perde motivação; review C1 calibra severidade.
- Crítica sem princípio: 'isso está ruim' é opinião; 'o princípio de DRY sugere' é engenharia.
- Crítica sem alternativa: reclamar sem propor caminho desmotiva; C1 sempre oferece alternativa.
- Misturar nit com blocker: o autor não sabe o que é urgente; sem calibração, ignora os dois.
- Linguagem passivo-agressiva: 'poderia ter feito melhor' soa pessoal; C1 foca no código, não na pessoa.
Prática guiada
Reescreva cada review abaixo no padrão C1.
- Nit vs blocker: rotule cada comentário por severidade.
- Mudança estrutural: cite o princípio (DRY, SRP, KISS) junto com a sugestão.
- Alternativa: sempre ofereça caminho, não só crítica.
- Linguagem calibrada: 'Blocker:', 'Suggestion:', 'Nit:', 'Question:'.
Resumo
Code review C1 calibra severidade (Nit / Suggestion / Blocker), cita princípios (DRY, SRP, KISS), propõe alternativas em vez de só criticar, e mantém a linguagem focada no código, não na pessoa. Review com princípio + alternativa é review que ensina; review sem eles é opinião.
Vocabulário
Palavras principais
'Blocker: this query has no index.'
'Blocker: esta query não tem índice.'The principle of DRY suggests extracting this helper.
O princípio de DRY sugere extrair este helper.SRP suggests this class has too many responsibilities.
SRP sugere que esta classe tem responsabilidades demais.KISS would suggest removing this abstraction.
KISS sugeriria remover esta abstração.Code review in C1 calibrates severity.
Code review em C1 calibra a severidade.História
História: Code review C1: depth and tact
Nível: C1
História em inglês
Reviewing a junior engineer's PR with depth and tact
On Wednesday, I had to review a junior engineer's PR for the user service. I opened with: blocker, the query has no index; in production it will scan 10M rows. I added a suggestion: could we extract this validation into a helper? It is repeated in 3 places, and the principle of DRY suggests a single source of truth. I closed with two nits: nit, extra blank line on line 42; nit, function name could be more descriptive. The engineer thanked me for the calibrations: now I know what is urgent and what is cosmetic.
Tradução linha por linha
| Inglês | Tradução |
|---|---|
| On Wednesday, I had to review a junior engineer's PR for the user service. | Na quarta, eu tive que revisar o PR de uma engenheira júnior para o serviço de usuário. |
| I opened with: blocker, the query has no index; in production it will scan 10M rows. | Eu abri com: blocker, a query não tem índice; em produção vai escanear 10 milhões de linhas. |
| I added a suggestion: could we extract this validation into a helper? It is repeated in 3 places, and the principle of DRY suggests a single source of truth. | Eu adicionei uma sugestão: podemos extrair essa validação em um helper? Está repetida em 3 lugares, e o princípio de DRY sugere uma única fonte de verdade. |
| I closed with two nits: nit, extra blank line on line 42; nit, function name could be more descriptive. | Eu fechei com dois nits: nit, linha em branco extra na linha 42; nit, o nome da função poderia ser mais descritivo. |
| The engineer thanked me for the calibrations: now I know what is urgent and what is cosmetic. | A engenheira agradeceu pelas calibrações: agora sei o que é urgente e o que é cosmético. |
Notas de vocabulário
- blocker, the query has no index; in production it will scan 10M rows = blocker com impacto em produção.
- could we extract this validation into a helper? principle of DRY = sugestão com princípio e pergunta aberta.
- nit, extra blank line; nit, function name = nits rotulados explicitamente como cosméticos.
- thank you for the calibrations = sinal de maturidade C1: severidade rotulada.
Perguntas de compreensão
- Por que diferenciar nit de blocker em C1?
- O que torna uma crítica C1 útil?
- O que deve ser evitado em code review C1?
Prática com a história
- Escreva um comentário de code review C1 para uma query sem índice.
- Escreva um comentário de code review C1 para código duplicado.
- Escreva um comentário de code review C1 calibrando severidade.
Prática
Exercícios e teste
A próxima melhoria é transformar esses arquivos em perguntas com resposta no navegador. Por enquanto, esta página já organiza o estudo e permite seguir a aula inteira sem abrir os arquivos manualmente.