Originally Published on March, 2023
🕒 5 min read
We've all been there - that sinking feeling when you realize there's another code review waiting for you. The thought of digging through someone else's changes, deciphering unfamiliar logic, and verifying edge cases... it's enough to make even seasoned engineers procrastinate.
I've felt that dread more than once. You delay the review, the pull request (PR) author grows impatient, and before long, your Slack starts lighting up with pings. Sure, there are those rare PRs that are a joy to review, clean, clear, and well-explained, but let's be honest, they’re the exception, not the rule.
This isn’t a one-off problem. In fact, it’s something I’ve seen at every company I’ve worked for. Code reviews become a chore instead of a valuable, collaborative process. So at one workplace, we decided to tackle this head-on by introducing a simple, structured solution: a **PR template**.
Rather than enforcing strict PR size limits (which often creates more friction), we focused on clarity. We required all PR authors to fill out a templated description that provided context, explanation, and evidence. Here’s what the template looked like:
# What
Ticket: [JIRA-1234](https://link-to-ticket)
# How
### Problem
Describe the issue from a user’s perspective.
### Reason
Explain the root cause of the problem.
### Solution
Describe how you addressed the issue in the code.
### Result
Include evidence of the fix (e.g., screenshots, logs, video clips).
This simple addition made a huge difference. It gave reviewers the context they needed to understand the change before reading a single line of code. It shifted the tone of reviews from defensive and vague to collaborative and focused.
Even better, if a PR was too complex to be explained with this format, it signaled that it should probably be broken down into smaller, more manageable PRs, and that’s a win in itself.
Code reviews shouldn’t be dreaded. With just a little structure and communication up front, they can become one of the most valuable parts of the development process, a place for learning, collaboration, and improvement.
Make it easy to review, and you’ll get better reviews and better code.
Until next time..
- Bardur