Mastering the Art of Code Review
Code reviews are a cornerstone of modern software development, but they are often misunderstood.
Even though it may appear otherwise, the goal is not to find fault with your code. The goal is to collaborate on creating better, more maintainable code.
Here's what I’ve learned works really well when I’m seeking code review from better coders than I (especially at Google - links to Google's Code Review Guides are later in this article).
1. Craft the Perfect CL (Change List) Description
A Change List is what we call a Pull Request in Google. They’re the same thing.
Start with the description. It is your first and best chance to provide context. Do not assume the reviewer knows what you know. Unless you know they know.
A good CL description becomes a permanent record of a change and should answer three key questions:
-
What is being changed?
-
Why is this change necessary?
-
What context led to this change?
Start with a short, imperative summary on the first line (e.g., "Fix: Prevent crash on login screen"). This is what appears in the version control history (i.e., the git commit history), so it needs to be clear and standalone. Be thoughtful. Because commit histories are extremely important during code audits, debugging regressions, etc.
The body of the description should provide more detail, including any relevant bug numbers or design document links. Link to GitHub issues, or other public resources that may be useful as context.
2. Embrace Small, Focused Changes
The single most effective way to improve your code review experience is to submit small, single-purpose changes.
I cannot emphasise this enough.
You’re not trying to impress with the quantity of code. You’re going to impress with the quality of engineering thought.
Small CLs are:
-
Faster to Review: Reviewers can fit them into their busy schedules and get them done quickly.
-
Less Prone to Bugs: It's easier for both you and the reviewer to reason about the impact of a small change.
-
Easier to Merge: Fewer conflicts mean a smoother integration into the main codebase.
-
Easier to debug and roll back: Smaller changes can be unwound faster than larger ones that involve too many other parts of the code base. It’s easier to uproot a small weed than it is to remove a tree.
Don't be afraid to split up a large feature into several smaller, dependent changes. This technique, known as "stacking," allows you to move forward while waiting for a review on an earlier change. You can also separate refactoring from new feature work, making each review easier to understand.
3. Respond to Comments with Composure and Clarity
Reviewer comments are not personal attacks; they are opportunities to improve your code. When you receive feedback, approach it with a calm, collaborative mindset.
-
Don't Get Defensive: If a comment feels frustrating, step away and come back to it with a cool head. The goal is to improve the codebase, not to win an argument.
-
Clarify the Code, Not Just the Comment: If a reviewer doesn't understand your code, your first action should be to improve the code itself or add a comment to make it clearer for future readers.
-
Engage in Discussion: If you disagree with a suggestion, explain your reasoning respectfully. Discuss the pros and cons of different approaches to reach a consensus. If a conflict persists, it may be time to involve a third party.
By mastering these three areas, you can transform the code review process into a collaborative and productive part of your development workflow. Most importantly, you will learn to think like an engineer, not just type like one.
And as promised here are (some) of Google's guidelines on good code review.
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)
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...😝
