Mastering Code Reviews (There's More!)

← Back to all posts

The code review is a fundamental ritual in modern software development. It's the moment where a solitary act of coding becomes a collaborative act of engineering.

For this process to be truly effective, both the developer submitting the code and the reviewer scrutinizing it must operate with shared principles. These principles were mandatory reading for all of us at Google. (Btw if you're interested in an experienced engineer's surprise at the sheer level of tooling and infra at Google read this post!)

Unlike the previous post which was target at junior devs, this guide is for both sides of the pull request.

We will first explore how a developer can submit code that builds trust and earns respect. That's Part 1.

Then in Part 2, further below, we will look at how a reviewer can provide feedback that elevates the codebase and mentors their team.

Part I: The Developer's Playbook for Submitting Code

Your pull request (PR) is more than just a code drop; it’s a signal. It tells your team about your discipline, your attention to detail, and your engineering maturity. A well-crafted PR builds trust and streamlines the entire process.

1. Your Description Is Your Calling Card

Don't just say "fixed bug." Your description is your narrative. It will live on in the commit history forever.

Be Specific: Start with a short, imperative summary on the first line. A title like "Fix: Prevent crash on login screen" is infinitely more useful than a vague one.
Provide Context: Your reviewer does not live inside your head. Use the body of the description to explain the why. Why was this change needed? What problem does it solve? Link to relevant issues, design documents, or external resources. A good description costs you time upfront, but it saves the reviewer—and future developers—an immense amount of time.
Add Visuals: For UI-related changes, include screenshots or even a short GIF. This visual context drastically reduces the cognitive load on the reviewer, making it easier to confirm the change's intent and appearance.
Self-Review First: Before submitting, review your own code. Read through the changes, check for typos, and ensure your tests pass. This simple step catches most low-hanging fruit and shows respect for your reviewer's time.

2. Small Changes Make a Big Difference

Monster PRs are a red flag. They are not thoughtful; they are thoughtless. As a rule of thumb, if a PR seems too big, it probably is.

Clarity over Quantity: Small, single-purpose changes are easier to read, quicker to review, and far less likely to introduce bugs. They demonstrate that you have broken a complex problem down into manageable, logical pieces.
Streamline Your Workflow: Small changes allow you to get continuous feedback without blocking your progress. You can submit one change, get it reviewed, and immediately start work on the next, creating a steady, efficient workflow. If you have to, separate refactoring from a new feature.
Use the Right Tools: Learn to use features like git add --patch or git rebase -i to create clean, logical commits that tell a coherent story, making the PR a narrative rather than a jumble of changes.

3. Feedback is Food for Thought

Code reviews are a process, not a personal critique. They are a form of informal mentorship from a fellow developer who is investing their time to help you improve.

Don't Get Defensive: If a comment feels frustrating, take a step back. Re-read it calmly. The goal is to improve the code, not to win an argument.
Clarify the Code, Not Just the Comment: If a reviewer doesn’t understand something, your code is probably not clear enough. Rather than simply explaining it in a comment, see it as an opportunity to improve the code itself or add a concise code comment to benefit all future readers. This is how you level up.
Ask for Clarification: If a comment is vague, ask for more details. For example, "This doesn't look good" is not helpful. Ask, "Could you explain why? I'm trying to understand the concern."

Part II: The Reviewer's Guide to Providing Feedback

A good reviewer is a guardian of the codebase. Your role is not to simply find errors, but to ensure the overall code health improves with every change.

1. The Reviewer’s Standard

Your primary goal is to approve a change that improves the system. You should always be aiming for continuous improvement, not unattainable perfection.

Prioritize Big-Picture Health: Focus on the overall design, functionality, and clarity. Does the change make sense? Is it simple? Is it well-tested? A developer should review no more than 200-400 lines of code at a time to remain effective.
Favor Approval: If a change is a net positive for the codebase, approve it. Minor stylistic nits or nitpicks can be labeled as such to avoid blocking the change.
Use Checklists: Establish a review checklist with your team that covers key areas like functionality, security, test coverage, and adherence to standards. This ensures consistency and thoroughness.

2. How to Look for Excellence

Your review should be a comprehensive check, not just a quick scan. Here’s what you should be looking for:

Architectural Impact: Does the code fit cleanly into the existing system? Does it introduce technical debt or conform to established patterns?
Security & Performance: Check for potential vulnerabilities like SQL injection or inefficient algorithms.
Testing: Are there tests? Are they robust and well-designed? Does the test coverage adequately address the changes?

3. Write Comments That Build, Not Break

Your feedback is your primary tool. Use it wisely.

Be Kind and Respectful: Your comments are about the code, not the person. Always maintain a professional and encouraging tone. Acknowledge what you like, especially if you have several suggestions for improvement.
Explain Your Reasoning: Instead of just saying "change this," explain why it should be changed. Providing context helps the developer learn and grow. You can point out a problem and let them find the solution, which may even be a better one.
Use Labels: Label comments by severity (e.g., Nit: for minor style issues, Suggestion: for optional improvements, Required: for critical changes). This helps the developer prioritize and understand the urgency of your feedback.
Focus on the Code: Frame your comments around the code, not the coder. Instead of "You didn't close the connection here," try "The connection does not appear to be closed in this function."

Five ways we can help you:

1. Wondering what learning to code actually means?

Becoming a coder is much more than just "learning to code" some languages. When I was hired at Google, for example, I didn't know three out of the four languages I had to write every day.

If you're still wondering if coding is right for you, then I recommend:

👉 My FreeCodeCamp Course --> Before You Learn To Code (Video).

👉 Updated version (including Google and other big tech experiences)

--> check it out here.

2. Inner Circle (Free Preview Included)

Our personalized, intensive mentorship program is designed to help career changers go from zero to software developer—and get hired. It’s not for everyone, but if you’re ready to commit, we’ll walk with you every step.

👉Preview the Inner Circle Program -> free preview.

👉Apply for Inner Circle → parsity.io/inner-circle

3. Dev30

Want to learn the basics, but not quite ready for the Parsity Inner Circle? No problems - Try the Dev30 challenge!

It’s our 30-day JavaScript sprint focused on building real projects, learning in public, and creating a network in tech.

👉Join dev30 → dev30.xyz

4. Career Change To Code Podcast

Driving? At the gym? Hiding in the bathroom? Perfect time to inject the best techniques for a career change to code directly into your brain via

👉 Follow the podcast here: YouTube | Spotify

5. Weekly Tips In Your Inbox

👉 Subscribe to this newsletter (it’s free). I try and keep it to 3 minutes or less so you can read in the elevator, waiting in lines, in the bathroom...😝