5.3 Code Review And Engineering Feedback

Code review is not a ceremony for proving who is smarter. It is a feedback system for risk, maintainability, shared standards, and knowledge transfer.

A strong review culture is both direct and humane.

What review should catch

Good reviews look for:

• Behavioral bugs.
• Missing edge cases.
• Security or privacy risks.
• Poor boundaries.
• Confusing names.
• Missing tests.
• Migration and rollout risk.
• Inconsistent user-facing behavior.

Style matters too, but style should be automated where possible. Human review attention is scarce.

How to write useful comments

Helpful review comments usually include:

• Location: what exact line, behavior, or design decision?
• Risk: what can go wrong?
• Evidence: why do you believe it?
• Suggestion: what action would improve it?
• Severity: must change or optional improvement?

Keep PRs reviewable

Large PRs make everyone worse at review. They hide behavior changes among refactors, formatting, and generated files.

Prefer:

• One behavior change per PR when possible.
• Separate mechanical refactors from functional changes.
• Screenshots or examples for UI behavior.
• Test notes that explain what was and was not covered.
• Early draft PRs for design feedback.

Review is where implementation becomes team-owned.