Written feedback that teaches

Nível: C1

Objetivo

Transformar code review em aprendizado em C1 com principle, example, alternative e rationale. O foco é feedback escrito que o autor entende, aplica, e lembra — não 'isso está errado' sem caminho.

Explicação

Feedback escrito que ensina em C1 segue uma estrutura fixa: principle, example, alternative, rationale. Cada bloco tem função própria.

1. Principle

Cite o princípio de design por trás do feedback. C1 cita: 'SRP suggests each class has one responsibility' ou 'KISS would suggest removing the indirection'. Princípio é o que generaliza o feedback para o próximo caso.

2. Example

Mostre o trecho concreto. C1 cita: 'this method does three things: validates the input, persists to the database, and sends the email'. Example ancoral o princípio no código real.

3. Alternative

Ofereça caminho. C1 cita: 'what do you think about extracting the validation into a helper, and keeping the persistence in a separate class?' Alternative é o que transforma crítica em colaboração.

4. Rationale

Explique o porquê. C1 cita: 'this will reduce the time to add a new validation rule from 1 day to 1 hour, and it will make the test surface smaller'. Rationale mostra o ganho, não só a opinião.

A frase C1 canônica: 'Following the principle of SRP, this method does three things (validate, persist, send email). What do you think about extracting the validation into a helper? This will reduce the time to add a new rule from 1 day to 1 hour.'

Exemplos

Erros comuns

• Feedback sem princípio: 'isso está errado' é opinião; 'SRP sugere' é ensino.
• Sem example: 'esse código é ruim' é genérico; 'este método faz três coisas' é específico.
• Sem alternative: reclamar sem propor caminho desmotiva; C1 sempre oferece alternativa.
• Sem rationale: 'eu acho melhor' é opinião; 'isso reduz o tempo de 1 dia para 1 hora' é ensino.
• Misturar feedback pessoal com técnico: 'você sempre faz isso' é pessoal; 'este padrão' é técnico.

Prática guiada

Reescreva cada feedback abaixo no padrão C1.

1. Principle: cite o princípio (SRP, KISS, DRY) como justificativa.
2. Example: mostre o trecho concreto que viola o princípio.
3. Alternative: ofereça caminho aberto, não fechado.
4. Rationale: explique o ganho mensurável.

Resumo

Feedback escrito C1 tem quatro blocos: principle (SRP, KISS, DRY), example (trecho concreto), alternative (caminho aberto), rationale (ganho mensurável). Sem princípio, é opinião; sem alternative, é reclamação; sem rationale, é 'eu acho melhor'.

História: Written feedback that teaches

Nível: C1

História em inglês

Reviewing a junior engineer's PR with feedback that teaches

On Thursday, I had to review a junior engineer's PR with feedback that would teach, not just block. I opened with principle + example: following the principle of SRP, this method does three things: validates the input, persists to the database, and sends the email. I offered an alternative: what do you think about extracting the validation into a helper, and keeping the persistence in a separate class? I added the rationale: this will reduce the time to add a new validation rule from 1 day to 1 hour, and it will make the test surface smaller. The engineer thanked me for the structure: now I understand the principle, not just the fix.

Tradução linha por linha

Notas de vocabulário

• following the principle of SRP = principle: regra de design.
• this method does three things: validates, persists, sends email = example: trecho concreto.
• what do you think about extracting = alternative: pergunta aberta.
• reduce the time from 1 day to 1 hour = rationale: ganho mensurável.

Perguntas de compreensão

1. Qual é a estrutura C1 de feedback que ensina?
2. O que diferencia princípio de opinião?
3. Por que oferecer alternative em feedback?

Prática com a história

1. Escreva um feedback C1 com principle, example, alternative, rationale.
2. Escreva um feedback C1 com principle + rationale para abstração sem ganho.
3. Reescreva 'isso está errado' como feedback que ensina.