Code reviews are a cornerstone of healthy software engineering teams. They catch bugs, share knowledge, and maintain code quality. However, the way we communicate during a review can either build up a team or break down morale. Writing actionable and constructive pull request (PR) comments is a skill that requires empathy, clarity, and precision.

In this guide, we will explore best practices for leaving PR comments that help your peers improve their code without feeling attacked, while also looking at how modern tools can automate the tedious parts of the process.

1. Assume Positive Intent

When reading someone else's code, it is easy to assume that a mistake was made out of carelessness. Always start with the assumption that the author did their best with the context they had.

Instead of asking, "Why did you do it this way?", try phrasing it as a genuine question: "Could you help me understand the reasoning behind this approach?" This subtle shift in tone invites discussion rather than defensiveness.

2. Be Specific and Actionable

Vague comments like "This looks messy" or "Needs improvement" are frustrating because they do not provide a clear path forward. If you spot an issue, explain exactly what is wrong and how to fix it.

Instead of: "Refactor this function."

Try: "This function is getting quite long and handles both data fetching and formatting. Could we split the formatting logic into a separate utility function to improve testability?"

When you provide specific suggestions, you reduce the back-and-forth required to resolve the comment.

3. Explain the "Why"

It is not enough to just point out a problem or suggest a change. You must also explain why the change is necessary. Are you suggesting a different approach for performance reasons, maintainability, or readability?

Providing the "why" turns a simple critique into a learning opportunity. If you reference a specific design pattern, documentation page, or internal style guide, link to it directly.

4. Differentiate Between Suggestions and Blockers

Not every comment needs to block a PR from being merged. It is crucial to clearly distinguish between critical issues that must be fixed and minor suggestions that can be ignored or addressed later.

Many teams use Conventional Comments to add prefixes to their feedback:

  • issue: A problem that must be fixed before merging.
  • suggestion: An idea for improvement that is highly recommended but not strictly required.
  • question: A request for clarification.
  • nit: A minor issue (like a typo or formatting preference) that is non-blocking.

By labeling your comments, you set clear expectations for the author.

5. Praise Good Code

Code reviews should not be entirely negative. If you see a particularly elegant solution, a well-written test, or a clever optimization, call it out! Positive feedback builds trust and reinforces good coding practices across the team.

Let AI Handle the Objective Checks

While the practices above are essential for human to human interaction, humans should not be spending their time pointing out missing semicolons, obvious typos, or stylistic inconsistencies. Reviewing code takes significant cognitive energy, and reviewers should focus on architecture, business logic, and systemic impacts.

This is where AI-assisted code review comes in. By automating objective checks, teams can ensure that PRs are clean before a human ever looks at them.

Codra is designed precisely for this. Completely self-hosted across Cloudflare Workers, Docker, or Node.js runtimes, Codra is a private AI code review engine for GitHub PRs. It allows teams to bring their own model (ensuring complete data sovereignty) and uses multi-pass filtering to drastically reduce comment noise. When Codra handles the objective, routine checks, developers are freed up to leave meaningful, high-level, and truly constructive comments on the things that matter most.

Conclusion

Writing great PR comments is about striking the right balance between rigorous engineering standards and human empathy. Be clear, be kind, and provide actionable feedback. By mastering this skill (and letting tools like Codra handle the tedious checks), you can turn code review from a dreaded chore into a powerful driver of team growth.