Ten commandments for the PR author
Code review is more important than ever in the cursor-and-copilot world. Notes for engineers, new and tenured, on how to be the kind of author whose PRs get reviewed without dread.
This is a writeup I originally circulated inside my team. I’m publishing a lightly adapted version here because the principles travel.
Motivation
As a tenured engineer I find myself reviewing a steady stream of PRs each week. This piece is motivated by recent experiences, by patterns I’ve watched accumulate over years, and by a growing need for quality in our work and our processes. As any team expands, so does the diversity of engineering backgrounds, levels of experience, varying exposure, and different norms carried over from past organizations.
It’s important to keep talking about these things, especially on remote teams where new folks can’t “learn by shoulder-surfing.” There’s no senior engineer’s screen for them to glance at across the desk. The process is the apprenticeship.
You’ve heard the famous Linus Torvalds line, “Talk is cheap. Show me the code.” In the Cursor and Copilot and code-gen world, that doesn’t hold the way it used to. Code is cheap now. Which means the code review process is more important than ever. We have to pick and choose right, and we have to convincingly justify each change.
That’s why I wrote this. To give engineers, new and experienced, a clear picture of what code reviews are actually for and the guiding principles for the process.
Why code reviews?
I won’t state the obvious about why code reviews matter for development quality. Let me instead address the pessimistic view. Code reviews are not designed to slow you down, gatekeep, or red-tape contributions. That’s not what they’re for.
They’re crucial for sharing knowledge that isn’t easily transferred over meetings or high-level design discussions. They’re opportunities for information dissemination and for junior engineers to grow. They should never, ever feel adversarial.
PR discussions are productive work, not a formality to get your code stamped. They are important conversations in their own right. I have had numerous moments of quiet enlightenment when someone has asked a question on a code change that hadn’t crossed my mind. And just as often, I’ve been staring at lines of code in a repo that didn’t make sense, traced the original PR, read through the discussion, and had every rationale fall into place.
This matters even more when you’re on call for a connector or service you didn’t contribute to. If you’re trying to demystify a code change in production at 2am, a properly explained and justified PR is the difference between “back to sleep in ten minutes” and “still digging at 4am.”
PRs are also a valuable artifact for your own track record. A well-documented PR is proof of thoughtful engineering. Strong technical discussions build credibility and relationships.
Ten commandments for the author
1. Don’t dump giant PRs
Keep them small, focused, scoped to a single task. Large PRs are hard to review and easy to procrastinate on. See stacked diffs if you haven’t already.
The company’s most valuable resource is engineering time. Treat your teammates’ time with that respect.
2. Write a meaningful PR description and title
Explain the what and the why. Mention design decisions, trade-offs, approaches considered. Follow the template if your repo has one.
It is 100% your job to justify and explain the change. It is not the reviewer’s job to dig up that context. You are closing the knowledge gap between your deep context and everyone else’s, so we can optimize globally rather than locally. If the reviewer has to ask “can you fill in the description?”, that’s a waste of their time and a waste of yours.
Believe me, you’ll thank yourself six months later when you’re trying to demystify why you did what you did.
For bigger changes, link the design doc. Be conscious of not blowing up the PR description with everything; if there’s a lot of content, give a tl;dr and link out to a verbose wiki page.
3. Make it easy to review
Organise changes logically. Carve out separate PRs if unrelated changes have crept in. Triple-check everything before you ask for a review. Make it so people look forward to reviewing your code, not dread it.
You are anticipating the reviewer’s needs and making their job easier through thoughtful preparation. That’s the whole thing.
4. Test before you request review
Run the code. Run the tests. Add new ones. You should prove it works, and mention what and how you tested. Thorough testing is the practical commitment to shipping software that doesn’t break for your customers.
5. Lint your code
Free up your reviewers to focus on what matters: the logic and impact of your change. Please handle all linting and style issues beforehand so they don’t have to spend valuable time on minor, automatable nitpicks.
Arguing about style is wasteful. Using automated tools is tasteful.
6. Address all comments gracefully
Acknowledge each comment, whether by fixing it, discussing it, or explaining why not. Avoid silent changes. Do not ask for a second pass until you’ve done this. The reviewer should not have to decipher whether a new commit addressed their feedback.
For junior engineers especially: don’t be defensive. Nobody is judging you and the reviewer is not trying to “win.” Assume good intent. A PR with lots of comments isn’t a bad sign. It usually means the work is meaningful and the team cares about doing it well.
One more thing: do not conflate PR reviews with change-advisory-board (CAB) reviews. PRs are for ensuring quality, addressing blindspots, thinking through edge cases and rollout strategies. CAB review is the last line of defense for prod changes. It’s there to validate that the right thinking has already happened, not to start it. A well-prepared engineer walks into a CAB review with a solid plan already documented in the PR, and just needs to walk the team through it.
7. Help reviewers help you
Highlight the tricky parts. Add inline comments to explain non-obvious code. Call out things that are intentionally deferred to future PRs.
Ensure all technical discussion lives in the PR. If you discussed something on Slack, leave a summary on the PR. Slack messages get lost. The PR is the durable transcript.
The PR becomes an asset that serves the team today and in the future. Be a good ancestor.
8. Ping responsibly
Tag reviewers only after the PR is truly ready for a pass. Not just “the code is committed.” Ready means: older comments replied to, PR description and title elaborated, intent clear. If it’s WIP and you want early thoughts, say so explicitly.
And show your appreciation for the reviewer’s time. It’s not easy to context-switch and spend time on something totally tangential to your own planned work.
9. Plan for code reviews
Don’t drop a PR on Friday evening and say you want it merged by Monday’s CAB review. PR reviews take time and mental energy, and reviewers don’t have enough notice or planned bandwidth for that.
It’s on you to plan for multiple review rounds, time to make changes, and discussion time. Poor planning on your part should not become the reviewer’s problem. If your plan requires quick turnaround, give a heads-up ahead of time and use the assignee feature on GitHub to secure dedicated bandwidth.
10. Own the code change
In every sense of the word “own” it. It’s your change and you are responsible for ensuring it works. The reviewer is there to assist and catch blind spots, not to absolve you of ownership. A senior reviewer’s stamp does not mean your job is done and everything is perfect.
“Done” doesn’t end at PR submission. It ends when your change is working successfully for the people who depend on it. Your ownership drives that result.
If this resonates, I’ll follow up with a companion piece aimed at the reviewer side of the table, where there’s just as much room for improvement.