Reviewing code is an essential skill for professional developers. If you're going to work in a team, you'll be expected to review other developers' code.
Most junior programmers I talk to find it daunting to start doing code reviews. Imposter syndrome starts to rear its head. After all, when you're a junior, how are you expected to provide great feedback to a more senior developer? How do you know you're looking for the right things?
Reviewing code is also an under-appreciated skill, and one that isn't usually taught. Regardless of whether you went through a bootcamp or CS program, or you're a self-taught developer, you typically learn code reviewing by doing it. And more often than not, you learn by having your code reviewed and then trying to emulate what you've seen others do.
This post aims to highlight key aspects to focus on during a code review and offering guidance on providing constructive feedback. This isn't the definitive resource - there's been a lot written about code reviews, including entire books.
Much of this post comes from Curricular's internal code review guidelines. At Curricular, we spend a great deal of our time reviewing projects, to help up-and-coming developers continue improving. To make our reviews as helpful as possible, and ensure our feedback is generally consistent across multiple reviewers, we've established internal code review guidelines and best practices. We've tailored those guidelines towards junior developers for this post.
Understanding Code Reviews
A code review is a phase in the development process where you, as a reviewer, check another developer's code to identify errors, ensure adherence to coding standards, and suggest improvements.
Typically, you’ll review a small change to the codebase, like a single issue.
The review is only partially about catching bugs; it's also an avenue for reinforcing best practices, ensuring consistency, and fostering a culture of collective ownership and continuous learning.
Most organizations and open source projects create their own standards and expectations around code reviews. Generally speaking, these standards are designed to aid collaboration and help teams move quickly. Code reviews are typically about improving the quality of code and fostering healthy discussions, without creating too many bottlenecks and slowing down development velocity.
How Doing Code Reviews Benefits Junior Developers
It’s one thing to receive feedback on code you’ve written. That’s for another post. Our focus here is on the benefits of reviewing other developers’ code.
As a junior, code reviews are a chance to sharpen your knowledge of a codebase, your communication skills, your understanding of best practices, and begin contributing to the team.
To do a great code review, you’ll typically need to spend some time learning about the surrounding codebase to understand how someone’s commit will interact with other components in a system (features, models, tests, etc.). This can, in turn, expose you to programming paradigms you may have only heard or read about, because as a junior, you probably haven’t worked on many distributed systems or microservices. Code reviews are therefore a great chance to learn up close.
Additionally, you can learn best practices. By observing how more experienced colleagues write and structure their code, you can learn effective coding practices firsthand. Development teams typically try to follow style guidelines, so code reviews are also a great orientation to how things are done within the specific context you’re working in. And whether you’re joining a new company or contributing to open source, you’ll be expected to conform to the established style guidelines, and to catch when someone else’s code doesn’t follow conventions.
Finally, performing code reviews helps to hone communication and critical thinking skills. At a certain point, technical skills will only get you so far in your career. To maximize your potential as a developer, you’ll need excellent soft skills as well. Code reviews require clear communication, attention to detail, and well-phrased questions and comments - essential skills for progressing to more senior levels.
What to Look for in a Code Review
Here are some of the key things to look for in a code review.
- Correctness: Is the code doing what it's supposed to do? Verify logic, edge cases, and error handling to ensure the code meets its requirements. Also check to make sure there aren't any unintended side effects.
- Readability: Assess the code for clarity and simplicity. Examine things like naming conventions, spacing, code structure, and check whether they follow best practices and the organization's style guidelines. When in doubt, ask for clarification, because chances are if you’re confused, someone else will be down the line.
- Performance: Look for any potential bottlenecks or inefficiencies. Is there a way to simplify the code while still solving the problem?
- Best Practices: Ensure the code follows industry and project-specific best practices. This includes design patterns, SOLID principles, DRY, and avoiding anti-patterns. Nothing scores you points with senior developers like catching and removing an anti-pattern.
- Testing: Evaluate the coverage and quality of unit tests and integration tests, ensuring they are meaningful and robust. And ensure any impacted existing automated tests are also updated.
- Security: Watch out for potential vulnerabilities, such as SQL injections, XSS, or data exposure. Depending on the seniority of the developer, it's probably rare to find something this glaring, but it's important to check.
Giving Great Feedback
Providing great feedback is an art. The best feedback focuses on the most important issues, fosters healthy conversations, and leaves both the code and the developer in a better place. Here are some things to focus on with your feedback:
Point Out the Good Parts, Too
If you catch someone doing something right, point it out. That will reinforce best practices, and also balance out the areas for improvement.
Be Specific and Constructive
Point out specific parts and suggest how they could be improved. Clarify which issues you feel strongly about and which you don’t.
Ask Questions
Instead of mandating changes ("you should" or "this needs"), ask questions that provoke thought, such as, "Could this loop be replaced with a map function for better readability?"
Provide Context
When suggesting changes, explain why. This helps the author learn and understand the reasoning behind your feedback, making it more valuable.
Focus on the Code, Not the Coder
Keep your language neutral and focused on the code. Use "we" instead of "you." And avoid humor and sarcasm. Bear in mind that tone is difficult to infer in online discussions. Unless it’s incredibly obvious, it’s better to keep it neutral.
Consider Sync Communication
If you notice recurring issues or have a more philosophical topic for feedback, consider a short video call to discuss in detail.
Don’t be a gatekeeper
Your job is to suggest changes; ultimately the owner of the PR will decide whether it gets approved.
Code Review Scenarios
Finally, it's important to consider the setting of a code review. Different contexts require difference approaches.
Code Reviews Within a Team
In team settings, the goal is to maintain a cohesive codebase and ensure all members are aligned with the project's coding standards and practices. Juniors should leverage these reviews to understand team-specific conventions and seek feedback on their contributions.
Tailoring your approach
Aim for constructive feedback, emphasizing how suggestions align with team practices. Don’t shy away from constructive feedback on more senior team members’ code - your contribution is important. But focus on asking questions for clarity until you get comfortable with the team’s norms.
Code Reviews on Open Source Projects
Reviewing code in open source projects can be a great way for juniors to get involved with new technologies and communities. Here, the emphasis might be more on adhering to the project's contribution guidelines and understanding the community's expectations.
Tailoring your approach
Be respectful of community norms and more conservative in suggesting changes, focusing on clear, documented issues or enhancements.
Code Reviews on Side Projects
When reviewing code for side projects, possibly with peers at a similar level, the purpose of the code review is probably more about mutual learning and checking for errors. This kind of code review can be more informal, offering a safe space for experimentation and discussion.
Tailoring your approach
There are probably fewer established guidelines within the codebase, so you might need to allow for more variance. Be sure to point out which issues are most significant to address. Ask lots of questions and explain context when suggesting changes. Consider leaning into more synchronous discussions to dive deeper into the strategies used and ways to improve.
Additional Resources
Code reviews are more art than science, and the only way to get truly great is with practice.
If you want to learn more, check out these other great resources on code reviews:
An oldie but goodie about how one developer approaches code reviews
Every organization treats code reviews slightly differently, so you'll want to adjust your style to fit the context where you're working. Here’s an example for how Palantir thinks about code reviews, which also contains tons of helpful links
Top comments (0)