Tutorial 3: Give Feedback That Lands

Reviews are communication, not corrections. Tone determines whether feedback gets applied or resented.

Step 1: Comment on the Code, Not the Author (10 min)

✓ "This function does too many things; consider splitting."
✗ "You're making this too complicated."

✓ "I'd expect this to handle null inputs."
✗ "You forgot to handle null."

The author chose. The choice can be discussed. The author's competence isn't on trial.

Step 2: Ask, Don't Tell (10 min)

✓ "Why use a map here instead of a list?"
✗ "Use a list here."

Questions invite explanation. Sometimes the author has a reason you missed. Sometimes asking the question is enough to make them reconsider.

Especially powerful when you're not 100% sure your suggestion is better.

Step 3: Be Specific (5 min)

✓ "This recursive call can stack-overflow at ~10K items; consider iterative."
✗ "This won't scale."

✓ "If `user.is_admin` is false, the next line throws."
✗ "There's a bug here."

Specific = actionable. Vague = handwaving.

Step 4: Suggest a Fix (When You Can) (10 min)

✓ "Consider:
   ```python
   return next((u for u in users if u.active), None)

" ✗ "This loop is ugly."

GitHub suggestions (`suggestion` blocks) let the author apply your code with one click.

Suggestions move the conversation forward. Critiques only stall it.

## Step 5: Soften with Caveats (5 min)

"Maybe consider..." "I might be wrong, but..." "What do you think about..." "Just a thought..."

Some style guides hate these as "weasel words." For reviews: they reduce defensiveness. The technical point lands; the ego doesn't bristle.

Use sparingly. Too soft = ignored.

## Step 6: Praise Specifically (5 min)

✓ "Nice — the early return makes the happy path obvious." ✗ "Looks good."

Specific praise teaches. Vague praise feels patronizing.

For new team members: extra praise on good patterns. They learn what's valued.

## Step 7: Don't Pile On (10 min)

If another reviewer already raised an issue, don't repeat it.

"Agree with @alice — this needs handling for empty input."

Or just thumbs-up Alice's comment.

Multiple voices saying the same thing feels like an avalanche.

## Step 8: Acknowledge Trade-offs (10 min)

✓ "This pulls in a heavy dep. If we can't avoid it, fine; otherwise consider inlining." ✗ "Don't use this dep."

Real engineering involves trade-offs. Acknowledge.

If you're missing context (e.g., why they chose this approach), ask before declaring.

## Step 9: Pick Your Battles (5 min)

A PR with 20 small issues:

- Comment on the 3-5 most important
- Let the rest go

Or:

- Approve with suggestions
- Trust the author for follow-up

Drowning the author in nits creates resistance to **any** feedback.

## Step 10: Read Your Comments Before Sending (5 min)

Before submitting your review, re-read your comments:

- Tone OK? Not condescending?
- Wording clear?
- Did you say something you'd regret in writing?

Take 30 seconds. Edit.

For tough feedback: walk away; read again later.

## What You Just Did

Feedback that lands: code not author, ask don't tell, specific, suggest fixes, soften, specific praise, no pile-on, trade-offs, pick battles, re-read. Reviews that build relationships.

## Common Failure Modes

**Comment on the person.** Defensiveness; team friction.

**Vague feedback.** Author doesn't know what to fix.

**Pile-on with other reviewers.** Author feels attacked.

**No suggestions; only critiques.** Slows iteration.

**Hot review under stress.** Regret later.