Code review is a collaborative way for developers to share knowledge and help each other and a best practice to improve the overall quality of software, educate developers, and ensure consistency across evolving code bases. What I can tell you is that there’s no standard way to do a code review. Every team at every company has unique requirements and expectations of the code and the review.
At Swimm, knowledge sharing is a core value. So today, I’m walking through the benefits of a code review process, what we do at Swimm, and sharing a checklist for the reviewer and reviewee including my thoughts on how and why it works.
The benefits of code reviews
The benefits of code review are numerous; let’s dive in!
Code reviews get better results
Successful pull requests go hand in hand with a solid code review process. Ultimately, code reviews make products better.
Code reviews are traditionally done before merging a pull request into a branch. Some startups are growing so quickly and have such demanding timelines that market delivery is a higher priority than quality. Those teams build features quickly, get them to market, and do a code review following deployment.
At Swimm, devs review code before merging into our main branch. It’s an essential step before going to production and gives us more eyes on the code. Our priorities are high code quality, consistent use of best practices, and shared knowledge.
Developers learn best from hands-on experience and our code reviews make that happen. When developers are more knowledgeable and informed, their feature and bug fix implementations also improve. We don’t use code reviews to find bugs because reviews aren’t tests. Code reviews help us think about the bigger picture and ensure that we are creating high-quality, readable code.
Code reviews help build teams
As an engineering manager, I’ve found that code reviews can be part of building a successful and functional team for sharing knowledge. It’s one of the best tools to create conversations between peers. Code reviews also build a sense of team since the members will review each other’s code and support each other.
Engineering managers should set the right expectations for code reviews and validate these guidelines with their team. If there aren’t already company guidelines for the code review process, discussing and defining the process with your team is worthwhile so that everyone is on board. The procedures and best practices need to be agreed upon – because it’s not a unilateral decision. The whole team needs to buy in.
Finally, engineering managers should be available to help or participate in a code review, lead by example, and encourage the team to take on code reviews themselves.
Code reviews are opportunities for communication and improvement
One of the most important aspects of a code review is open-mindedness. This can be challenging for developers. Just because a reviewer thinks, “We can do this differently” doesn’t mean it’s a better way. Because the likelihood is high that there may be something the implementer knew or discovered that the reviewer hasn’t yet thought of.
For our team of devs at Swimm, it boils down to communication. If we feel like the code review becomes a long “ping pong” game of comments in a pull request or the reviewer uncover a major problem, we address it directly on Zoom or face to face. We try to avoid these situations by keeping PRs small so reviews are more concrete.
Maintaining a strong company culture is one of the ways that we’re successfully building and growing Swimm. Reviewing code together should build team trust, not dismantle it. Suggesting changes is great, but the way we recommend them is just as important. A central goal for code reviews is to motivate, not discourage; judgmental comments undermine the entire review.
I like to think of code reviews as a kind of checks and balances; the checks and balances are equally important.
Creating a code review process at Swimm
Whether reviewing code before or after deployment, it’s important to check for syntax, best practices, and overall code readability. Some senior developers write very efficient code, but it might not be as readable and efficient. Other developers may write inefficient code that needs the eyes of a senior developer to improve the implementation or approach. A junior developer’s code usually requires a more thorough review for these scenarios.
In terms of creating a code review guide process for our team at Swimm, here are four takeaways.
- Most of the details about a code review depend on the size of the change itself. For example, we usually pair a single reviewer with the person getting their code reviewed. At Swimm, code reviews are often open to developers who wish to participate in the conversation and the process. It is not uncommon that the entire team will work together to generate more ideas and feedback.
- Larger code bases usually have subject matter experts for certain parts of the code. There’s nothing wrong with this, but at Swimm, we try to switch up who does code reviews for the expert. As an engineering manager, I wouldn’t want the same person doing reviews all the time just because they are “seniors” or just because they are the manager. I would like people from the team to be able to review each other’s code – which helps share knowledge, create technical conversation – and reduce bottlenecks.
- More significant changes may require a larger group or more eyes on the code. Especially when changes affect another team’s code, we also ask for input from another team to get additional perspectives.
- It’s important to balance learning with making improvements. During code reviews, we prioritize learning, but when we need to release a hotfix or deliver a quick update urgently, we recognize the importance of having a more senior developer participate in the code review and implementation of the feature. Because, of course, we’re a startup too.
Large features require more prep
We do prep work before writing code for complex new features requiring a lot of research. For example, we’ll have a technical design review, talk with other departments, and discuss the technical solution before writing a single line. This reduces many issues during code reviews and stops them from exploding.
Moreover, when developers and product managers are aligned with the product flow before implementing new features, the foundation of this plan, coupled with open communication, significantly reduces friction. Not to mention that the number of bugs also dramatically decreases.
At this point, we are very careful to limit the sizes of our PRs. We’ve found that “micro PRs” is the best way to mitigate code review issues.
Micro PRs make code review easier
Micro PRs are small, can be reviewed fast, and are easily understood, whereas PRs with more than 50 file changes are too hard to understand.
With micro PRs, we rarely have to review too many files at a time. Each time a micro PR can go into a feature branch, we merge it until the entire feature is ready. Then we merge it, and we know that all the code has been reviewed at that point. This improves communication and helps everyone feel comfortable that the change meets all our functional and non-functional requirements.
Code review checklists
Though code reviews are typically straightforward, sometimes they require more attention because there is a larger task to address. At Swimm, for example, while migrating from Vue2 to Vue3, we are involving more of our team in the surrounding code reviews.
Code review checklist for the reviewer
#1 Focus on the critical issues. In giving feedback during a code review, decide what’s most important. Too many comments can be confusing in the same way that too many files can be hard to review.
- Code quality – Guidelines for documentation, code readability, quality, and testing should be agreed upon in your R&D teams. Make sure the code is readable, covered by tests, and well documented. Our “future selves” and team will be grateful for not bulking up technical debts.
- Velocity – If you notice issues that are non-blockers for the PR to be merged, ask to open a ticket for addressing them in a separated PR. Dev velocity is critical for a project’s success; stale PRs can lead to slower delivery, frustration, and difficult merge conflicts.
- Balance – There is a thin line between velocity and quality. Maintaining a balance between the two while seeing the bigger picture is important.
#2 Check that all requested requirements are met. This includes both product requirements and R&D requirements. The code (aka – the solution) must address the product/tech issue (aka- the challenge) and be robust, following agreed-upon best practices.
#3 Prioritize communication and learning. Remember that code reviews are an excellent tool for learning. Even as a reviewer, you need to be open-minded and trust the reviewee that they took some implementation decisions after thinking about them. Ask the reviewee to explain if the “why” isn’t clear enough.
Code review checklist for the reviewee
#1 Focus on the problem you’re solving. The PR should solve a problem. Have other enhancements/ changes? Do it in another PR.
#2 Check the code quality – Follow the agreed-upon R&D guidelines. Readable code, good testing, and documentation are crucial for future maintenance.
#3 Share as much context as needed. Attach the product ticket/useful information to the PR for context. With Swimm’s GitHub App and Swimm Doc Hooks, we get recommendations for docs that are relevant to the PR!
#4 Keep communication a top priority. Be open-minded. Code reviews are an opportunity to learn, make changes, and build confidence in giving and receiving feedback to make the product more robust.
#5 Follow-up after merging:
- Let the relevant “customers” know that the work is done (PM/EM/UX/Sales..). If it’s possible, ask for feedback.
- If any “TODO” tickets were opened during the CR process, make sure to address them one by one.
Swimm’s Doc Hook in action
How Swimm uses Swimm to help with code reviews
We like to practice what we preach and reap the benefits of our own platform. When it comes to code reviews, Swimm (the product) is a major help to Swimm (the company) developers.
- Every pull request is tested to ensure that docs are available for new code. And since every reviewer doesn’t know the whole codebase by heart, Swimm makes it easy to understand what’s happening at the file and function-level granularity.
- If something is missed in the code review, Swimm can notify the team and let them manage or respond to that notification. This is especially useful for code that’s had production incidents. It might mean new docs are needed or existing docs need updating. The person submitting the PR can be sure everything is covered, and so can the reviewer.
- Developers open a PR and identify with Swimm’s algorithm where documentation should be added. For example, if there is a PR, Swimm’s GitHub app notifies you that documentation should be written. All of this can be discussed and handled during a code review.
Bottom line
Swimm is a knowledge-sharing platform, and code reviews are one of the ways it happens. Knowledge sharing through code reviews strengthens our engineering capabilities and gives our teams ownership of our mutual success.
Learn more about how engineering teams are using Swimm to keep documentation efforts updated and aligned with the code itself. Coupling code with documentation reduces the risk of repeat incidents, increases the speed of developer onboarding, and keeps our code readable, maintainable, and high-quality. Add all of that with a code review process, and you are good to go.
