Introduction

Code review is a very important part of developers' daily routine. Each day, developers allocate a portion of their time to preparing their code for review and evaluating the code submitted by others.

Engaging in good code reviews offers a valuable opportunity for both personal and team development.

They ensure that the code we write is functional and high-quality, and contribute to a culture of excellence and continuous improvement.

Whether you’re the author of the code or one of the reviewers, understanding and adhering to effective review practices is crucial for achieving the best outcomes.

The benefits of code reviews for a team

Code reviews offer a range of benefits that can significantly improve both the quality of your code and the dynamics of your team. Here’s why incorporating code reviews into your workflow is so important:

• Fewer Bugs: By having multiple sets of eyes on the code, you reduce the risk of bugs going unnoticed. This proactive approach ensures that the final product is more reliable and less prone to issues.

• Shared ownership: It becomes a collective responsibility rather than just the author’s. This collaborative approach means that everyone on the team has a stake in the quality of the code, leading to better overall results.

• Enhanced Collaboration: encourage thoughtful discussions and diverse opinions. This process helps identify knowledge gaps and fosters a collaborative environment where developers can learn from each other. It’s an opportunity for team members to engage in meaningful debates, share insights, and contribute to better solutions.

• Effective coaching: For junior developers, code reviews are an excellent opportunity for learning and growth. More experienced developers can provide guidance, explain problem-solving strategies, and help less experienced team members develop their skills.

• Increased Accountability: When developers know their code will be reviewed by others, they are more likely to put in the extra effort to ensure its quality. Without this accountability, it’s easier to let standards slip. Regular code reviews ensure that everyone maintains high standards, resulting in more robust and reliable code.

Indicators of a poor code review process

A well-functioning code review process is crucial for maintaining high-quality software. However, there are several signs that your code review process might be falling short. Identifying these issues early can help you address them and improve your development workflow. Here are some common indicators of a poor code review process:

• Large queue of minor bug reports: If you consistently find yourself dealing with a large number of minor bug reports every time you release new features, it might indicate that your code review process is not catching these issues. While some bugs are inevitable, frequent small problems suggest that code reviews are not being thorough enough to identify and resolve these issues before they reach production.

• They make you anxious: Feeling anxious when opening a code review can be a red flag. If you’re worried about the feedback you’ll receive, it may mean that your team’s review process is creating a stressful environment. This could be due to harsh criticism, poor communication, or a lack of constructive feedback.

• Lack of comments: A review process where comments are rare might suggest that reviews are not being conducted thoroughly. If your team is approving pull requests (PRs) without providing feedback, it could indicate a lack of engagement or diligence in the review process.

• Too many review cycles: This might indicate that the changes being reviewed are too large or complex, or that reviewers are not providing clear and actionable feedback.

• Frequent Back-and-Forth: Too much back-and-forth during code reviews can signal poor communication between reviewers and authors. If discussions are dragging on without resolution, it may be due to unclear or inadequate feedback. Effective communication is key to resolving issues quickly and moving forward with the development process.

Key elements of an effective code review process

Synchronous or asynchronous?

Synchronous

Synchronous code reviews are particularly useful for handling fragile changes, those involving critical, untested parts of the system or areas that are challenging to test. In these cases, collaborating in real-time allows the team to ensure that changes are made safely. They are also beneficial for large and complex changes where the author needs to walk the reviewer through the code.

However, synchronous reviews are less effective for finding subtle flaws and defects, as these require deep focus and time, which is often challenging in a live discussion. Additionally, synchronous reviews can impact individual productivity because having two people working on the code simultaneously means less time for each person to focus on other tasks.

Asynchronous

On the other hand, asynchronous code reviews are better suited for individual productivity. When an author sends their code for review, they can continue working on other projects while waiting for feedback. This type of review allows each participant to focus more deeply on their task, whether it’s writing code or reviewing.

The process of writing comments during an asynchronous review helps in clarifying thoughts and delivering more structured feedback. Moreover, asynchronous reviews offer a fresh perspective since reviewers have the time to thoroughly examine the code, providing valuable insights into readability and potential flaws that might otherwise be missed in a live review.

As an author

When preparing a pull request (PR) for review, there are several key expectations to ensure the process is smooth and effective.

Firstly, the PR should be small. Smaller PRs are easier to review, less risky, and simpler to roll back if issues arise. A more manageable size helps reviewers focus on the code, making it easier to spot defects or flaws. Additionally, if a large PR is rejected, it means more wasted work compared to a smaller one.

The PR should also be appropriately scoped. It should address a single, specific goal or problem. A well-scoped PR ensures clarity and makes it easier for reviewers to understand the intended changes and their purpose.

Ensure that the PR is functional and includes tests. Before merging, the code should be tested thoroughly to confirm that it works as expected and is ready for production. It should pass all builds and checks to be considered production-ready.

The PR must be deployable and easily rolled back if necessary. It should be clear whether any refactoring is included, as different teams have varying policies on incremental refactoring.

In terms of documentation, the PR should include a detailed description. This should cover the intent of the code, the problem it addresses, how to reproduce the issue, and any relevant references such as issue tickets or related PRs. Additionally, include details about the tests, any migrations needed, and specifications on backward compatibility. If applicable, provide screen captures or recordings of the functionality to offer a clearer view of the changes.

Finally, assign the PR to the appropriate reviewer, ideally someone familiar with the changes being made. As the author, you are responsible for driving resolutions to any conflicts or issues that arise during the review process.

By following these guidelines, you help ensure that your code review process is efficient, effective, and collaborative.

As a Reviewer

As a reviewer, you play a crucial role in the code review process.

Firstly, accept ownership and responsibility. When reviewing code, approach it as if you were the one writing it. This mindset helps ensure that you provide thorough and thoughtful feedback.

Review code promptly. Avoid letting PRs sit for days or weeks. Prioritizing code reviews in the morning and after lunch can help unblock your teammates so they can address your feedback or proceed with their work.

Maintain high standards in your reviews, but favor pragmatism over perfectionism. Focus on whether the code works, solves the problem, and improves the overall health of the codebase. Minor performance optimizations can be handled in follow-up PRs and shouldn’t prevent the current PR from being merged.

Be kind and respectful in your interactions. Kindness fosters an environment of empathetic listening and mutual respect. If you’ve learned something from the review, share that feedback with the author.

Provide constructive feedback tailored to the author’s level and the context of the situation. Always offer a clear justification for any issues that might block the PR, such as excessive size, potential flaws, lack of tests, or over-engineering.

Specify whether comments are blocking or non-blocking. For instance, comments on minor issues like variable names should be marked as non-blocking.

Ensure that your comments are clear and concise, so the author can easily understand your intent. Focus on the code itself rather than making personal remarks about the author. For writing effective comments, consider following the Conventional Comments guidelines. Remember to leave positive comments as well. Recognizing and praising good work helps motivate and encourage your teammates.

An example:

// Bad
"This function it's unreadable, refactor it."

// Good
"suggestion (readability, non-blocking): Could we improve the readability of this function? Adding more comments might also benefit the team for future changes."

Code Review Guidelines

Establishing clear code review guidelines is essential for maintaining an effective and efficient review process. Here’s a list of elements to consider including in your code review guidelines:

1. When and How to Open a Code Review: Define the proper timing and procedures for initiating a code review. This should cover when to submit a PR and the steps to follow to ensure it’s ready for review.

2. Size and Scope of PRs: Set guidelines for the ideal size and scope of pull requests. Small, focused PRs are generally easier to review and manage. Specify how to scope PRs effectively to address specific goals or issues.

3. Author and Reviewer Expectations: Outline the responsibilities and expectations for both authors and reviewers. This includes what authors should include in their PRs and what reviewers should focus on during their reviews.

4. PR Templates: Provide templates to standardize the information included in pull requests. Templates should help authors include necessary details such as the purpose of the change, how to test it, and relevant links.

5. Escalation Procedures: Establish clear procedures for handling disagreements or conflicts during the review process. Define who to contact or how to escalate issues if disagreements cannot be resolved between the author and reviewer.

6. When and When Not to Refactor: Specify guidelines for refactoring code within a PR. Clarify when refactoring is appropriate, such as improving code readability or addressing technical debt, and when it should be deferred to avoid bloating the scope of the PR.

By incorporating these elements into your code review guidelines, you create a structured approach that promotes clarity, efficiency, and collaboration in the code review process.

What to look for in a code review

Before diving into the code itself, there are a few preliminary checks to ensure the review process starts on the right foot:

First, determine if the change is appropriately scoped. The PR should be focused on a specific goal or problem, avoiding unnecessary complexity. Next, verify that the build and tests have passed, ensuring that the code doesn’t introduce new issues. Check for any conflicts with the existing codebase that could cause integration problems. For UI changes, review any provided screenshots or recordings to visualize the changes. Lastly, confirm that the code changes effectively address the intended problem.

As a reviewer, it’s important to take ownership and responsibility for the code you approve. By approving a PR, you’re essentially putting your name on it, signaling that you believe it’s ready for production, as if you wrote the code yourself.

Key areas to focus on during the code review

When reviewing the code, start by looking for any potential flaws. These are the most critical issues, as flaws can cause significant problems if they make it to production. Pay attention to missed edge cases and corner cases, which might not be covered by the initial implementation.

Ensure that the code includes adequate testing, particularly unit tests, to validate its functionality. Also, watch for any gaps in business requirements, especially edge cases that might not have been explicitly defined by the business. Check for any unexpected behavior changes, such as potential issues with client interactions if an API has been modified.

Another key aspect is to verify that the code does not introduce any security vulnerabilities. This includes reviewing for common security issues like injection flaws, insecure data handling, and improper authentication or authorization checks.

Optimization is another important aspect. Review the code for any opportunities to improve performance. Additionally, ensure that the code is well-documented, readable, and not overly complex or over-engineered, making it easier for others to maintain and extend.

Post-Review Considerations

After completing your review, there are a few final checks to ensure the changes are solid. Confirm that the changes don’t introduce any unexpected side effects that could impact other parts of the system. The changes should be backward compatible, ensuring they don’t break existing functionality. Finally, assess whether the PR can be easily rolled back if necessary.

Remember, code reviews aren’t just about identifying issues, they’re also valuable learning opportunities. Be open to learning from the code you review and from the feedback exchanged during the process.

Conclusion

Code reviews are more than just a routine check before merging code, they’re a crucial practice that enhances the quality, reliability, and maintainability of your software. Code reviews benefit both individual developers and the team as a whole.

By following the guidelines for authors and reviewers, prioritizing constructive feedback, and focusing on the key aspects of code quality, your team can build a robust code review process that drives better outcomes and a healthier codebase. Embrace code reviews not as a chore but as a vital step toward delivering high-quality software and continuously improving as a team.