👀 Effective Code Review: Show, Don’t Tell

Code review is an important part of the development process. But how often have you encountered comments like: “This is wrong”, “Redo it”, “Don’t do it this way”? And where is the explanation of why it’s wrong and how to do it right?

Good code review is when we provide the result, not just push the opponent.

The Problem with Typical Code Reviews

Imagine you received a comment like this:

“This function is too big, break it into parts”

What did you feel? Probably some irritation and confusion. Why is it big? How to break it? Into what parts? What should be in each?

Now imagine another version:

“This function does three different things: fetches data, processes it, and renders the result. You can split it into three functions: fetchUserData(), processUserData() and renderUserData(). This will simplify testing and improve readability.”

The difference is obvious. In the second case, you immediately understand the problem and get a concrete solution.

Principles of Effective Code Review

1. Always Suggest a Solution

Don’t just point out the problem, show how to solve it. Instead of:

// Bad
Bad variable naming

Write:

// Good
The variable `d` is not obvious. Better to name it `userData` or `response` so it's clear what it contains.

2. Explain “Why”, Not Just “What”

// Bad
Don't use var
 
// Good
Better to use `let` or `const` instead of `var` because they have block scope and prevent hoisting errors.

3. Give Concrete Examples

// Bad
Complex logic, can be simplified
 
// Good
Can be simplified using array methods:
const activeUsers = users
  .filter(user => user.isActive)
  .map(user => user.name);

Templates for Effective Comments

Template 1: Improvement Suggestion

“Currently [problem]. Can be improved by [solution]. This will give [benefit].”

Example:

“Currently the component makes several network requests at once. Can be combined into one using Promise.all(). This will reduce the number of requests and speed up loading.”

Template 2: Problem Explanation

“[Code] can lead to [problem] because [reason]. Better to use [solution] because [advantage].”

Example:

“Using any in TypeScript disables type checking and can lead to runtime errors. Better to specify concrete types or use unknown with subsequent checking.”

Template 3: Alternative Solution

“Instead of [current approach] can use [alternative]. Here’s an example: [code]. This is better because [advantage].”

Example:

“Instead of manually iterating through the array, you can use find(). Example:

const user = users.find(u => u.id === targetId);

This is shorter, clearer, and faster because find() stops at the first match.”

Effective Code Review Checklist

Before sending a comment, ask yourself:

✅ Have I clearly described the problem?
✅ Have I suggested a concrete solution?
✅ Have I explained why this is important?
✅ Have I indicated the benefits of the proposed solution?
✅ Have I maintained a respectful tone?

Benefits for the Team

When you provide results instead of just criticizing:

1. PR author grows faster — gets not only criticism but also knowledge
2. Team atmosphere improves — people feel support, not attack
3. Code quality increases — concrete suggestions are easier to implement
4. Team level rises — everyone learns from examples

Personal Experience: How I Learned to Do Effective Reviews

I used to write comments like: “Don’t do it this way”, “Redo it”, “Bad code”. Colleagues got irritated, PRs dragged on, and the team atmosphere worsened.

Then I realized: if I see a problem, I must show how to solve it. Since then I always:

1. Write what is wrong
2. Explain why it’s a problem
3. Show how to do it better
4. Sometimes give alternative options

The result didn’t take long. PRs started passing faster, colleagues began thanking me for reviews, and the code in the project became noticeably better.

Conclusion: Be the One You Want to See

Good code review is not about demonstrating your superiority, but helping others become better. Instead of throwing criticism at the windmill, show how to do better.

Don’t tell people how to run fast. Run fast yourself, and they will follow you.

Next time you do a code review, remember: your goal is not to win an argument, but to help the project and colleagues become better. Show the result, don’t just point out the problem. Your team will thank you.