As a software developer, the importance of code reviews cannot be overstated. These reviews allow a team member—or possibly several, depending on your project requirements—to scrutinize your code. This scrutiny helps spot potential issues that might have gone unnoticed, suggests possible improvements, and ensures that your code aligns with the project’s standards. In this post, I will delve into why preparing for a code review is as crucial as the review itself. Preparation is not just about refining your code; it is about valuing your coworkers’ time and fostering a culture of constructive feedback and continuous learning.
Preparing for a code review includes thoroughly checking that your code meets the required acceptance criteria, ensuring the quality and conciseness of your work, verifying functionality, adhering to style and formatting guidelines, running unit tests to maintain necessary code coverage, and documenting your efforts. These steps are vital for improving code quality and streamlining the process for your reviewers.
As you approach your code review, remember that adhering to the process outlined in this article, augmented by your company’s standards, processes, and practices, will help you deliver a more polished product. This is your final opportunity to quality-check your work, ensuring it solves the problem it was designed to address. The time and effort you invest not only improves the final product but also demonstrates your respect for your coworkers’ time. In our daily routines, we all juggle multiple responsibilities. By submitting a well-prepared pull request, you help ensure that the time your colleagues dedicate to reviewing your work is well spent, reinforcing a team dynamic that values efficiency and respect.
Begin the process by reviewing the code you are about to submit within the context of the changed files to make sure that your code solves the required problem, and finally as a diff. Viewing the code within a full context allows you to understand the changes as they will appear once merged, facilitating necessary refactoring for performance and readability. Viewing the code as a diff highlights every line you added or removed, allowing you to resolve typos and remove debug statements.
As you review your code, pay special care to the complexity of work. If the code is overly lengthy or complex and takes more than an hour to review, consider splitting it into multiple pull requests to make it easier to understand, discuss, and review.
Ensure that your code meets the acceptance criteria by reviewing all associated tickets and meeting notes. This step will help prevent back-and-forth discussions that can consume considerable time and effort. This is also a great time to ask clarifying questions regarding the ticket, or integration of your work into the codebase.
As you finalize your preparation, confirm that all unit tests run to completion and meet the required code coverage. It’s also prudent to merge the base branch—main, dev, etc.—into your current branch periodically to prevent merge conflicts, especially before submitting for review.
Finally, document your code, starting with the commit message and the associated ticket. Regardless of who will view the ticket, take the time to record your process, any challenges faced, decisions made, and provide tips or hints that could aid testers or reviewers in understanding your approach. Thorough documentation can foster more effective feedback and help others identify potential edge cases and scenarios you may have missed.
With this process complete, you can finally submit your code and brace yourself for feedback. In my first full-time job right out of college, I was optimistic that my initial review would earn high praise. Instead, my submission returned with more red marks than any paper I had ever written, leaving me disheartened. It was challenging not to take it personally; after all, did a few extra spaces or a differently named function really matter that much?
After some time digesting the feedback over comfort food, I re-engaged with the process and initiated a voice chat with the person who provided the feedback. This conversation helped me get to know my colleague better and resulted in valuable discussions. I came away from that call with a deeper understanding of the codebase and a renewed perspective. The lesson from this experience is clear: try not to take feedback personally. It’s often meant constructively, even if it’s tough to receive. If you find yourself struggling with feedback, reach out to the reviewer. Whether you’re in the office or working remotely, consider setting up a chat or a brief meeting to discuss their comments. This can transform feedback into a valuable learning opportunity and strengthen professional relationships.
Effective preparation for a code review reflects your dedication to both the project’s success and your professional relationships. By approaching each pull request with a thorough submission, you demonstrate respect for your colleagues’ time and contribute positively to the environment. This approach doesn’t just elevate the quality of the work; it builds a foundation of respect and collaboration that benefits the entire team.
As you implement these strategies, I would love to hear what has worked well for you, as well as any valuable feedback and insights you have gained through your own process in the comments. Stay tuned for my next article in this series, where we will explore the other side of the equation: performing code reviews!
Well written, Ty! I agree with almost everything. My only comment is that I hope developers write comments sooner in the dev process. Docs echo the design and usually reduce time spent coding and, as you mention, helps reviewers or someone looking at the code later understand your approach