A code review comment is a reviewer’s written observation, question, suggestion, or request about a code change. Effective feedback progresses the conversation, clarifies intent, or strengthens the team’s maintainability practices rather than creating conflict. section 6.0
Strong comments are objective, specific, and outcome-oriented. Tie a request to a work ticket, coding convention, observable flaw, or edge case instead of presenting personal preference as fact. section 6.1 section 6.1.1
Shape feedback according to the situation:
- Basic: identify the issue precisely and explain why it matters. section 6.1
- Improved: frame the request around the code, not the developer; use collaborative wording such as “Can we move the Vehicle class to a separate file?” section 6.2
- Advanced: state the review signal or requested action, connect it to a guideline or outcome, and leave room for discussion when reasonable alternatives exist. section 6.2 section 6.0
From preference to actionable feedback
Weak: “You should move the Vehicle class to a separate file.” Better: “Can we move the Vehicle class to a separate file? This follows our team guidelines and will improve the readability of this section.” The second version names the requested change, avoids a personal attack, and supplies a reason.
Avoiding empty approval
An “LGTM” approval on a large pull request can signal that the review was rushed or incomplete. A useful review should communicate what was examined and whether any actionable concerns remain. section 7.1.1
Figure 6.1 From a pull request for the materialize repo
Inspect the pull-request example to see how an unsupported implementation preference leaves the author to infer the reviewer’s reasoning. section 6.1.1
