Ultimate guide to PR review process

13 min readMay 7, 2026

Yeap, another article about PR reviews 😅. This one’s going to be a big one — however, it’s not for you guys, it’s for me. It’s a personal reminder on how to conduct reviews and document new projects. If you find it useful, great 😁! If not, that’s unfortunate 😔.

There are some general topics I would like to discuss:

What Is a Code Review?
Motivation
Knowledge Sharing
Who Should Review Your Code?
How Many Reviewers Should Be Assigned?

And give advice to each party:

Rules for the Team
Rules for Code Review Creators
Rules for Reviewers

Still, I hope you will like it. Let’s see 🙃.

What Is a Code Review?

A code review is the process of examining someone’s code before it’s merged into the main branch.

Motivation

Code reviews motivate developers to write high-quality code, knowing it will be examined by their peers:

Code reuse: Encourages leveraging existing functionality instead of reinventing the wheel.
Code style consistency: Reviewers ensure new code follows established style guides before it reaches the main branch.
Error detection: Reviewers help catch typos, legacy fragments, redundant comments, or stray console logs.
Bug reduction: Early feedback lowers the number of issues reaching production.
Less refactoring: Developers can address concerns before merging, reducing the need for later fixes.

Notice ⚠️:
Many teams choose to skip code reviews, believing they’re time-consuming and rarely catch significant bugs. They usually limit reviews to newcomers or less experienced developers. That approach can work. I’ve tried it myself, and it was actually refreshing, especially in a toxic environment where reviews focused more on blank lines than real issues. However, in a healthy, well-structured team, code reviews often prove their worth.

Knowledge Sharing

Code reviews foster continuous learning and team growth.

They create an environment where knowledge flows freely, encouraging everyone to become both a teacher and a learner:

Learn from Others: Reviewers discover new algorithms, patterns, and techniques by exploring different coding styles.
Reasoning Skills: Explaining and defending decisions helps developers think critically about their code and understand why one solution is better than another.
Gain Feedback: Authors receive valuable input and suggestions that can improve their skills and solution design.
Fresh Perspective: A new set of eyes can spot alternative approaches or potential improvements.
System Awareness: All participants become more familiar with the system’s new or modified components.

Who Should Review Your Code?

Ideally, every developer should regularly participate in the review process.

However, some teammates may have deeper expertise. It is recommended to assign:

A senior developer or architect capable of spotting structural and architectural issues.
Someone familiar with the functionality you’re modifying.
A responsible teammate you trust 🙃.

Do not overload the same reviewers with every pull request. Let’s let those people rest, for God’s sake 😭. Code reviews work best when everyone shares the load (and the blame) evenly across the team.

How Many Reviewers Should Be Assigned?

The optimal number of reviewers depends on the complexity and impact of the change.

For small fixes or minor updates, one reviewer is usually enough to ensure code quality and consistency.

For larger features, architectural updates, or critical modules, it’s best to have two reviewers, based on research.

Avoid overloading the process with too many reviewers, as it can slow down development and dilute responsibility. The goal is to maintain quality while keeping the feedback loop fast and focused.

Rules for the Team

As a team, you should establish your PR review process.

Ensure your PR review process is clearly documented and agreed upon by everybody. Meet with your team to define:

📏 PR Size & Structure

Maximum PR Size: Define the largest pull request each team member is comfortable reviewing. Smaller, frequent PRs are easier to review thoroughly.
Handling Large or Complex Features: Agree on splitting large features into multiple PRs and using intermediate reviews.

⏰ Review Timing

Review Turnaround Time: Set expectations for how quickly reviews should be completed.
Maximum Time Before Review: Agree on how long a PR can remain unreviewed.

I don’t even remember what I had for lunch today; if you ask me a week later why I wrote the code this way, I’d be explaining it to myself 😒!

👥 Roles & Assignments

Reviewer Assignment: Decide whether PRs are assigned to specific reviewers or rotated across the team.

🧾 Process & Standards

PR Template: Agree on mandatory checklist items for all PRs to ensure consistency in quality and style. Configure PR template for your repository:

✅ My code follows the style guidelines of this project
✅ I have performed a self-review of my own code
[] I have commented my code, particularly in hard-to-understand areas
[] My changes generate no new warnings
[] I have added tests that prove my fix is effective or that my feature works

                               . . .

Code Review Pyramid: Agree on a code review pyramid to focus on those parts that matter the most during a code review.

💬 Communication & Feedback

Commenting Guidelines: Standardize how to provide constructive feedback, including templates, tone, and when to escalate issues.
Conflict Resolution: Establish a clear process for disagreements between reviewers and authors.

⚙️ Automation & Quality Gates

Automated Checks: Determine which tasks (linters, formatters, tests, security checks) should be automated before human review.
Approval Criteria: Define what conditions must be met before a PR can be approved and merged.

Rules for Code Review Creators

A well-prepared author makes the review process smoother and more productive for everyone involved.

The author of a code review should follow these key rules to keep the process efficient and professional.

💡 Preparation

Prepare Before Submitting. Make sure your code compiles, there are no merge conflicts, it passes all tests, and follows the team’s style guide. Don’t submit half-done work.
Self-Review. Review your code first — check clarity, complexity, formatting, and tests. Fix what you can before submission. Seeing the full picture often helps you catch things you initially missed.

🤝 Collaboration

Resolving Comments. All reviewer comments must be addressed. It’s not acceptable to close the comments without discussion.
Communicate Clearly. If you disagree with feedback, discuss it respectfully and provide reasoning. The goal is collaboration, not debate.

🧠 Mindset

You Are Not Your Code. The purpose of a review is to improve the code, not to judge the developer. Expect feedback and remember — comments target the code, not you.
Learn from Feedback. Each review is an opportunity to improve. Pay attention to recurring comments — they often reveal areas where you can grow as a developer.

Rules for Reviewers

I found it more entertaining to review someone’s code than being reviewed. Creating a PR is easy; reviewing one is where the real challenge lies — and the real skill shows.

Where else would you be able to compare others to garbage to feel smarter yourself 😅. Therefore, let’s see a list of practices on how to do it professionally.

⚡ The Right Tone in Reviews

This may surprise you — especially if you’re the people-type — but sometimes a little tension is healthy.

Get iamprovidence’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

A good code review isn’t a tea party; it’s a constructive clash of ideas. When people like you too much, they may avoid challenging your decisions to keep the peace. But if they respect you — even if they occasionally dislike you — they’ll speak up. That’s where real technical growth happens.

The secret here is to be toxic just enough not to get fired.

Diamonds form under pressure; so does great code.

🤖 Automate Code Review

Before even starting a review, you should make sure it passes all automated checks.

I’ve worked with developers who’d spend hours pointing out in review formatting and syntax rules. What a waste of time and the customer’s money 😒. We’re developers, after all 😤. Spend five days to automate your five-minute routine 😁!

Here are some tasks worth automating:

This one is kind of obvious, but still, builds and unit tests should always be automated to catch errors early.
Branch, commit, PR name validation to keep naming consistent
Linters to enforce coding style rules.
Code formatters (beautifiers) to standardize formatting automatically.
Architecture and convention checks to ensure the code follows project structure rules, layer boundaries, and established naming or conventions.
Use automated code review tools that generate comments using code analysis or AI, like Codacy, SonarQube, etc
Find extensions that will help your project — for example, tools that automatically create work items when a TODO is detected in the code, etc.

Automated checks should be run at different stages to catch issues early and ensure code quality.

On-save actions: Automatically run linting, formatting, or basic static checks when the file is saved in the IDE.
Pre-commit or pre-push Git hooks: Perfect for repository-level rules (branch or commit name).
CI pipeline: Triggered when a pull request is created. Ideal for running builds, executing tests, and performing deeper analysis.

This lets the reviewer focus on what truly matters — logic, design, and architecture — instead of formatting or syntax.

🎯Understand the Purpose Before Reviewing

Code becomes far easier to understand when you know why it was written.

Begin by reading the ticket thoroughly and identifying the code that addresses the stated requirements.

Then, run the code to verify it actually works. You don’t need to act as QA or test every edge case — just make sure the main “happy path” functions as expected. Otherwise, you may approve good-looking code that doesn’t even work. What was even the point of doing the review?

🧐 What Should Be Reviewed

Focus on what truly matters — logic, redundant code to remove, design, convention, and architecture. The goal of a review isn’t to argue over spaces, bracket placement, or be nitpicky, but to ensure the code makes sense.

A good reviewer looks for clear logic, maintainable structure, and alignment with architectural standards.

✅ Have a Code Review Checklist

It’s easy to overlook important details during a code review, which is why having a checklist is crucial. A checklist ensures consistency, helps reviewers cover all key points, and makes the review process more thorough and effective.

It defines what must be verified in every pull request:

Git:
✅ Branch name is correct
️✅️️ Commits names are correct
️✅ PR name is correct
️✅ Work item is linked
✅️ Is the pull request merged into the correct branch

Code:
✅️ Folders / Files structure is reasonable
❌ Code is covered with tests
✅ Functions and variables are well-named 
️✅ No duplicated code 
️✅ Proper error handling 
[] Code is properly formatted
[] Input validation implemented 
[] Performance considerations addressed

Performances:
[] Are introduced changes scalable?
[] Will it cause performances issues?

Maintenance:
[] Do we have enough logging do debug on production?
[] Do logs contain enough details (entity ID, email, names, trace ID)?

DB:
[] Is the database structure (if any changes) correct?
[] Does it contain the correct constraints?
[] Is the naming for new tables/columns correct?

Security:
️✅️️️ Permissions are managed properly
[] No exposed secrets or API keys

Docs:
️✅ Documentation is created/updated if needed

The exact content depends on your team’s priorities, but it should cover everything you consider critical for stability, security, and readability.

And if you think some of the items can be automated, do it 🙃.

💻 Review Code in an IDE

Sure, reviewing code in a browser is faster, but try checking out the branch in your IDE instead.

Comparing branches lets you explore the file structure, navigate to references, and see where functions are declared.

Trust me — reviewing in an IDE is far more efficient than in a browser.

💬 When to Leave a Comment — and When Not

Learn to work in a team and accept non-ideal solutions. Only comment when one of the items in your checklist fails, the code affects functionality, readability, maintainability, performance, or security, or you found a bug.

Look for potential enhancements: new abstractions, reusable code, libraries, or better organization. Watch for overly complex logic, long methods, or code that relies on too many comments to explain itself.
Find a method full of nested conditionals, and suggest breaking it into smaller, well-named helper methods to make it cleaner and easier to follow.

Don’t demand a complete rewrite. First, understand why the current approach was chosen. If you genuinely have a better solution, discuss it with the team — but keep time management and priorities in mind.

Avoid commenting on minor stylistic preferences — automation already handles that.

🔥How to tell people their code is bad

Other people’s code will often seem worse — simply because it wasn’t written by you.

However, you can’t just tell someone their code is “bad”. For some reason, people tend to get upset (and this is a pure mystery to me) when you call their work pathetic 😒. You need to have good reasons for that. The key is to learn how to give feedback constructively.

Avoid vague or condescending comments. These phrases do more harm than good:

“Can you make it clearer?” assumes the code is unclear without explaining what is confusing.
“Why didn’t you write it this way?” implies the developer was wrong, careless, or lacked skills or knowledge.
“Do it differently/clearer/etc” gives no direction and leads to endless back-and-forth.

Be specific. Explain what’s wrong, why it’s a problem, and how it can be improved. Do not assume your solution is automatically better. Prove it.

Use a clear comment template:

Priority:
- Suggestions (consider improving)
- Warnings (should fix)
- Critical issues (must fix)

What is wrong: ***
Why it's wrong: ***
Suggested improvement: ***

This format helps the developer understand exactly what needs to be improved and why, and it helps the reviewer to improve reasoning skills.

Code can always be written differently — there’s more than one way to solve the same problem. Learn to clearly explain and justify your reasoning. If your proposed change adds little real value, it’s probably not worth leaving a comment. If you feel that something is wrong, but do not have any suggestions, maybe it is not worth writing a comment at all.

Of course, you can skip the template for obvious issues like types, formatting, or minor typos.

Make your comments easy to read to minimize misunderstandings.

❓ How to ask questions

If something in the code isn’t clear, ask. Questions reveal hidden issues, clarify intent, and often spark discussions that lead to better design and shared understanding.

However, asking questions feels bad sometimes because it can be interpreted as criticism — especially if phrased bluntly (“Why did you do it this way?” sounds like “You did it wrong”). Developers often tie their identity to their code, so even neutral questions can feel personal.

The key is how you ask. Prefer curiosity over accusation — e.g., “Can you help me understand why this approach was chosen?” assume positive intent — the author likely had a reason.

You might uncover the reasoning behind the decision — maybe it was based on outdated information, time pressure, limited experience, or constraints you weren’t aware of. Avoid assuming your approach is better unless you have solid evidence to support it.

🤝 Discuss Code Together with the Author

Even with a clear comment template, there is always a risk of miscommunication.

Written comments take time, and explanations lead to long threads. Just call the person, review together, and discuss. The author can clarify why a particular solution was chosen, avoiding weeks of back-and-forth.

💎 Learn from Bad Reviews

It’s often easier to learn from bad reviews than from good ones. Notice what irritates you when someone reviews your code — vague comments, harsh tone, or nitpicking. Remember how that feels, and make sure you don’t repeat the same mistakes when reviewing others’ work. Bad experiences can teach you how to give better, more respectful feedback.

Summary

Code reviews in pull requests aren’t just about catching obvious bugs — that’s what tests are for. A solid review uncovers design issues that could become serious problems later. Additionally, they strengthen collaboration and communication among developers while ensuring consistent quality across the project.

If you want to conduct a professional code review, switch to the branch and open the PR in your IDE, use a review template, avoid nitpicking, focus your comments on meaningful issues, have a good argument for each point, and discuss each comment to prevent misunderstandings.