My key points for code reviews

This article is part of my code review series. It focuses on the key areas I personally pay attention to when reviewing code — across roles, projects, and even AI-generated changes.

Reviewing code isn’t just about catching bugs. It’s about helping the team produce changes that are appropriate, understandable, and maintainable. Here’s what I actually look for — and why.

Suitability: Does This Belong Here?

Before looking at how something is implemented, I check whether it should be part of this pull request at all.

• Does the PR reflect the scope of the associated change request or bug ticket?
• Are unrelated improvements, refactors, or “cleanups” bundled in?
• Is this the right place in the codebase for this kind of change?

When working on a bug fix, it’s easy to pick up improvements in code that happens to be nearby. In principle, this is a good habit — but any change risks introducing new issues. If these non-essential changes block the PR, they can delay important fixes. Splitting them into a separate PR allows the team to merge what’s needed now and review the rest later. It also makes regressions easier to trace.oose to let the non-essential changes sit for a while. Smaller PRs also make it easier to track down regressions later.

Understandability: Do I (and Others) Get It?

Next, I ask myself: Do I understand what’s happening?

That includes:

• What changed?
• Why did it change?
• Is the logic easy to follow?

If I have to piece it together from scattered clues, that’s a red flag. If I struggle to follow the logic now, someone else — including future me — definitely will in a year.

Complex code isn’t always avoidable. But it should still be clear, well-named, and ideally supported by tests or comments when needed.

Respect, Investment, and Company Standards

Code can be personal — developers take pride in it, especially after solving something difficult. A review is not a place to prove you’re right. It’s a conversation about the code, not the coder.

• Balance opinion-based suggestions with what actually matters.
• Team or company standards take priority over personal taste.
• If you disagree with the standard, a PR comment is not the place to argue it — raise that separately.

Use positive, constructive language. The Google Code Review Guidelines are a great reference on how to give and receive feedback respectfully, and how to handle differences.

Whether writing or reading comments, always consider the other person involved. People have different communication styles — and when working across international teams, this gets even more complex. To keep things clear, agree on labels or phrasing that indicate the severity or intent of a comment, such as:

• Must change: Violation of standards, best practices, or likely bug
• Should change: Improvements for maintainability or clarity
• Question: The reviewer wants to understand the approach or logic

Review Comments: Clear, Helpful, and Contextual

A good review comment is like a mini bug report:

• What’s the concern?
• Why does it matter?
• (Optional) Suggestion or alternative

Comments should be tailored to the author’s experience level, but remember: everyone can read them later. Make them clear, kind, and to the point.

Avoid vague references like “same as above” — comment order isn’t guaranteed, and reading comments out of sequence is common. Instead, refer to the relevant file and line, or quote the code snippet.

And if a comment thread turns into a disagreement: take the discussion offline. PRs are not a great place to have debates — resolve it in person or in chat, and document the outcome briefly in the PR.

Supporting Artifacts: Test, Docs, and Config

Every change has ripple effects. I always check whether related artifacts are included:

• Are there tests for new behavior?
  Not just generic coverage — but meaningful tests, including edge cases. For bug fixes, test-first (TDD) is a great way to confirm the issue and prevent regression.
• Are configurations updated? This includes environment settings, deployment files, and feature flags.
• Is documentation updated where relevant? Especially important for breaking changes, manual configuration, or anything that impacts the user.

Yes, documentation tends to drift. But that’s often because it’s not reviewed alongside the code. Keeping docs close (in the repo) and including them in reviews reduces this problem.

What I Don’t Review (Manually)

I don’t waste time on formatting, indentation, or naming conventions — those are for automated tools. Human attention is better spent on logic, structure, and intent.

Let the tools handle the rest.
See Let the Tools Do Their Job for how to configure formatters, linters, and static analysis effectively.

Conclusion

Code reviews are not about perfection. They’re about maintaining trust in the codebase, improving clarity, and helping each other grow.

By focusing on what matters — suitability, clarity, respect, and supporting artifacts — and offloading repetitive checks to automation, we make reviews more valuable, less tedious, and easier to maintain over time.

This checklist is not a full process. It’s the lens I use in most projects. Use what fits your team, and adapt it to your context.