阅读中文版本

Review as Mentorship Workflow

Frame review comments to teach reasoning and standards so the team improves rather than just fixing this change.

Overview

Use code review to raise the team’s skill and shared standards, not just fix the current change.

This workflow is reusable across teams and environments; adapt the commands to your tooling while keeping the sequence and checkpoints intact.

Environment and prerequisites

• A respectful review culture
• Shared standards documentation
• A feedback channel

Procedure

1. Explain the why, not just the what

Pair each requested change with the reasoning so the author learns the principle.

Expected state: Comments teach transferable reasoning.

2. Distinguish must-fix from optional

Clearly label blocking issues versus suggestions so the author can prioritise.

Expected state: Authors know what is required versus nice to have.

3. Point to standards and examples

Reference the written standard or an existing example rather than personal preference.

Expected state: Feedback is grounded in shared standards, not taste.

4. Invite dialogue

Ask questions where intent is unclear instead of assuming error.

Expected state: Review becomes a conversation, not a verdict.

# label comment severity in the review
[blocking] this leaks the connection on error
[suggestion] consider extracting this helper

Verification

Confirm comments explain reasoning, requirements are distinguished from suggestions, and feedback references standards.

Decision points

Directive or teaching feedback?

• Explain the reasoning
• State the change only

Recommendation: Explain the reasoning; understanding prevents recurrence.

Block on style?

• Automate style, review for substance
• Block on style manually

Recommendation: Automate formatting and focus human review on substance.

Common failures

• Directive-only feedback does not teach.
• Mixing blocking and optional comments confuses priorities.
• Unexplained preferences frustrate authors.