Skip to main content
Home
HexagonalGuru

Code Review Without Friction: How to Review Faster, Better and Without Wars

HexagonalGuru's avatar

HexagonalGuru

Code Review Without Friction: How to Review Faster, Better and Without Wars

In a corner of the repository there's a pull request that's eleven days old. It has 43 comments: seventeen about formatting, nine about variable names, a philosophical argument about a pattern nobody uses, and a resigned "LGTM" from someone who no longer wanted to argue. The author has rebased four times and is starting to browse job offers. Meanwhile, the feature that fixed a real bug still hasn't reached production.

Code review is probably the practice with the best cost-benefit ratio in all of software development — and the one done worst when adopted without thinking. Done well, it catches errors before they cost money, spreads knowledge and raises the team's level. Done badly, it's a bottleneck with opinions. This guide is about keeping the first version.

What It's Really For (and What It Isn't)

Review has exactly three functions:

  1. Catching errors. A second pair of eyes sees the edge case the author had in front of them and couldn't see. It's the most obvious function and not the most valuable one.
  2. Spreading knowledge. The reviewer learns what that module does and how the problem was solved; the author gets another perspective. It's the function that pays the most in the long run: it turns individual knowledge into team property.
  3. Aligning criteria. Review is where the team implicitly negotiates how code gets written here. Without it, every developer writes their own dialect.

And what it isn't for: imposing the reviewer's personal style, proving who knows more, or substituting for tests. If the discussion is about taste, it isn't review: it's decoration. And if a bug could only be found by a person reading, the problem is the lack of tests, not the lack of review — as we saw in the testing pyramid, the first safety net is automatic.

The Rules of the Game That Change Everything

Anatomy of an effective code review: small pull requests, the author prepares the context, comments classified as blocking, suggestions and questions, and response in hours not days

Teams with healthy reviews share four unwritten rules — until they write them down:

  • Small pull requests. It's the variable that most influences review quality. With 200 changed lines, the reviewer reads; with 1,500, they scan. If the feature is big, split it into chained PRs that make sense separately. The practical rule: if the description needs more than five lines to explain the change, it's probably two PRs.
  • The author prepares the review. Before assigning reviewers: green tests, self-reviewed diff, and a description that explains the why — what problem it solves, which alternatives were discarded, where to look first. Reviewing without context is guessing; the well-prepared PR gets reviewed in half the time with twice the accuracy.
  • Classified comments. Every comment carries a label: blocking (must be changed or discussed), suggestion (the author decides), question (I want to understand). It removes 90% of the friction: nobody argues over a suggestion and nobody ignores a blocker.
  • Response in hours, not days. The ageing PR accumulates merge conflicts and wear. The healthy standard: first review within the same working day. If the team can't manage it, the problem isn't willingness — it's too much work in progress.

How to Comment Without Hurting (and Without Going Soft)

Friction rarely comes from the content of the comment: it comes from the form. A few guidelines that work:

  • Comment on the code, not the person. "This function mixes two responsibilities" instead of "you always write giant functions". The code belongs to the team; the moment the comment is personal, the review becomes defence.
  • Ask before asserting. "Is there a reason not to use the shared HTTP client here?" teaches more than "this is wrong", and sometimes reveals the author had a reason you couldn't see.
  • Propose, don't command. "How about extracting this into a method?" turns review into a technical conversation. And if the answer is "I'd rather leave it", the suggestion label forces you to accept it without reopening.
  • Praise the good, by name. "This test for the empty case is exactly the one we always forget" costs ten seconds and reinforces precisely the behaviour you want repeated. A review that only points out errors teaches people to hide them.
  • Important things get said in person. If a comment is going to need three replies, get up or call. Five minutes of conversation resolves what twenty comments inflame.

What to Review (and What to Leave to Machines)

The reviewer's attention is the scarce resource: spend it on what no tool can do.

To the machines: formatting, imports, linting, types, tests, coverage, static analysis, leaked secrets. All of that goes to CI and isn't debated in comments — as we said in Clean Code in real projects, the formatting war is won with a formatter, not with opinions.

To people: whether the design answers the problem, whether the names tell the truth, whether there are uncovered edge cases, whether the change breaks an assumption elsewhere in the system, whether the next person will understand this in six months. None of that gets automated by any linter.

Common Mistakes

  1. Review as customs control. A single senior reviewer who must approve everything isn't quality control: it's a bottleneck with a title. Two reviewers with clear criteria beat one omnipotent gatekeeper.
  2. Rewriting the other person's PR. "I would have done it differently" isn't a blocking criterion. If it works, it's tested and it's understandable, approve it even if it isn't your style.
  3. Mass nitpicking. Twenty formatting comments teach the author to fear review, not to write better. If formatting matters, it goes to CI; if it doesn't, let it through.
  4. Approving without reading. The reflex LGTM is worse than not reviewing: it gives the false security that someone looked. If there's no time, say so and reassign.
  5. Reviewing only the diff. The change can be correct line by line and break the whole module. Before approving, look at the context: who calls this, what assumptions did the surrounding code make.

In Short

Code review exists to catch errors, spread knowledge and align criteria — not to impose taste. It works when PRs are small, the author prepares the context, comments are classified and the first response arrives the same day. People review design and clarity; machines, formatting and tests. And tone matters as much as content: comment on the code, ask before asserting and praise the good. A review that frightens people doesn't raise quality: it hides it.

If reviews are slowing your team down or too many bugs reach production despite reviewing, we can review your process — and your code — and propose a concrete adjustment. Let's talk →

Keep reading: Technical debt: what it really is, when it's good and how to pay it down.

  • #quality
  • #code-review

Related articles

Shall we start?

Ready to build something that grows with your business?

Tell us your goals and together we will map the design, development and technology route that takes you from vision to measurable results.