An objective code review comment supports its suggestion with verifiable facts, requirements, conventions, use cases, or demonstrated effects. Alternative implementations are welcome when the reviewer can explain why they are better; unsupported personal preference is usually better left out. section 6.1.1 section 6.4
Before suggesting a change, use the 5P process:
- Pause: stop before writing the suggestion. section 6.1.1
- Ponder: identify what prompted the suggestion, whether it is necessary now, and whether objective facts justify it. section 6.1.1
- Pass when the suggestion is not valid; Propose when evidence supports a change; Postpone when the idea may matter but falls outside the current scope. section 6.1.1 section 6.4
Turn preference into evidence
Instead of writing, “Use my implementation,” explain the measurable advantage: “Could we use this implementation because it is faster? Here are comparison metrics.” Alternatively, cite the applicable language convention or team standard. A use case can also establish why the proposed behavior matters. section 6.1.1
Figure 6.4 The 5P process for suggesting a change during a code review
Use the 5P process as a compact decision aid before posting a suggested change. section 6.1.1
