Code reviews play a vital role in shaping the culture of engineering teams. At Plaid, we value inclusivity and collaboration, and we believe that establishing our own code review guidelines is an effective way to foster these principles as we grow as an organization.
Growing Together through Code Reviews
The code review process at Plaid is driven by two main objectives: facilitating learning and growth for all parties involved, and ensuring the delivery of high-quality code. As our team continues to expand, we recognize the need to scale our code review practices beyond direct relationships between engineers. While we have successfully scaled the act of writing code itself through the use of linters and style guides, we needed to develop a scalable approach to conducting code reviews.
To establish a comprehensive set of guidelines, we began by gathering insights from our engineering team. We interviewed a diverse range of engineers, from fresh graduates to seasoned professionals, and consolidated their ideas into a concise document. This document was then shared with the entire team, allowing everyone to contribute and have their voices heard. After achieving consensus, we presented the final guidelines during an all-hands engineering meeting to ensure alignment.
Plaid’s Code Review Guidelines
Goals of a Code Review
Approaching a code review with the right mindset is crucial for providing and receiving feedback constructively. Our primary goals are to maintain codebase health, ensure correctness, and foster mutual learning and growth.
For Authors
Respecting the reviewer’s time is the most important rule for code authors. This principle serves as the foundation for all other guidelines. When requesting a code review, authors should ensure that their code is ready for review. This includes running necessary tests, removing debugging statements, and providing contextual information in the review description. Clear motivations and explanations of how the code accomplishes its goals help reviewers and future engineers understand the code.
Effectively scoping the pull request (PR) facilitates an efficient code review process. Submitting hundreds of lines of code for review often indicates a need for more careful scoping. Beyond a certain threshold, usually a couple hundred lines, it becomes increasingly challenging for reviewers to fully comprehend the changes. Limiting the changes also speeds up the code review process, enabling faster shipping.
Finally, authors should appreciate the time reviewers dedicate to providing feedback and promptly respond to their comments, even if it’s just acknowledging that a suggested change has been made. We encourage the use of the ⚡️ emoji as a tool to track changes.
For Reviewers
Maintaining codebase health is a primary objective for code reviewers at Plaid. However, as style and readability are often subjective, it’s essential for reviewers to differentiate between opinions and objective facts. While code bugs can be objectively identified, suggestions related to code organization or variable naming are subjective and should be communicated accordingly.
Plaid has style guides for each programming language we use. If a reviewer wants to enforce specific practices in a codebase, such as alphabetizing imports in TypeScript repositories, it should be documented in the style guide. Global changes should be made through a pull request against the style guide, rather than reviewing every PR in every repository for that language. If a PR violates the style guide, reviewers should point to the specific violation and direct the author to fix it independently, rather than commenting on each violation line by line.
Reviewers should avoid focusing solely on small details (nits) during code reviews. Instead, they should view the code as a whole and assess how it integrates into the larger system. While nit comments may sometimes be necessary, they should not be the primary focus of the review.
While correctness is crucial, reviewers should remember that computers are more effective at catching bugs. It is equally important for reviewers to ensure that authors have written appropriate tests for any new code paths introduced.
For Everyone
At Plaid, we foster a “ship it” culture, with continuous deployments and global teams. Our work involves integrating with thousands of financial institutions, leading to frequent infrastructure changes. Consequently, there’s often a sense of urgency in code reviews. However, not all PRs have equal urgency, so it’s crucial to communicate timelines clearly when requesting a review.
The code review process provides an opportunity for constant growth and learning. Authors and reviewers should be open to discussion and willing to question existing approaches. However, it’s important to recognize when a discussion becomes excessive and address it appropriately.
Significant design decisions should be discussed before code is written, as code reviews are meant to resolve implementation details rather than major design or architectural choices. Unforeseen points of contention that require substantial discussion may indicate that a PR was not properly scoped. In such cases, taking the discussion offline and addressing it in real time is recommended. Regardless of the reason for a spiraling discussion, it’s essential to recognize and resolve it effectively.
Implementing the Guidelines
To onboard new hires and reinforce our code review culture, we have created a dedicated onboarding session that covers our guidelines. The session includes a GitHub walkthrough, allowing new team members to review recent PRs and familiarize themselves with our processes. By exposing new engineers to our code review culture from the start, we empower them to contribute to its development.
Onboarding new hires into the code review culture can be intimidating, as they must simultaneously learn cultural norms and receive critical feedback. Therefore, it is crucial to create a welcoming environment during the onboarding process.
At the end of the code review onboarding session, participants select a personal LGTM emoji, which symbolizes their stamp of approval for code reviews. This emoji is added to our internal engineering README, marking the beginning of their journey as code reviewers at Plaid. Welcoming new engineers as code reviewers from the outset is a key aspect of strengthening our code review culture.
While these guidelines will evolve alongside our engineering organization, we encourage team members to contribute, ensuring that the guidelines remain representative of our culture. While specific details may change, our ultimate goal remains the same: maintaining an inclusive and collaborative engineering culture.
If you find this approach interesting, we invite you to consider joining our team!
FAQs
Coming soon…
Conclusion
Code reviews are a powerful tool for fostering inclusive and collaborative engineering cultures. By establishing clear guidelines and fostering a culture of continuous learning and growth, Plaid ensures that code reviews remain a positive and effective part of our development process. We believe that investing in code review practices empowers our engineers and contributes to the success of our organization.