What Does a Good Code Review Look Like?

What Is a Code Review?

Code review is an essential part of the software development process, where developers review each other's code to ensure that it is of high quality, follows best practices, and is aligned with the project's goals. A good code review is thorough, constructive, and efficient and can significantly improve the quality of the codebase and the overall development process.

Why Do Code Reviews?

By adding another layer to the software development cycle, coworkers can catch bugs, make improvements to make the code more maintainable and scalable, and catch style guides that could have been better followed.

This process is there to serve you and the team. It's a win-win situation and not an assignment or a performance evaluation.

Though it adds an extra layer to the software process, that is more work to do which can slow you down. So your goal as someone who interacts with the code review process is to make it as frictionless and seamless as possible so it can achieve its goals.

Some of the goals that are achievable by code reviews:

• Find bugs
• Ensure code meets standards
• Increase tests coverage
• Ensure features are implemented according to specifications
• Check for potential performance or security problems
• Knowledge transfer
• Increase collective ownership

Anti-Patterns

Code review anti-patterns are behaviors or practices that can hinder the effectiveness of the code review process. Here are some common code review anti-patterns to avoid:

Nitpicking

Refers to the tendency to focus on minor details or flaws in the code, such as styling standards or formatting, rather than considering the bigger picture or the overall quality and effectiveness of the code.

Ongoing debate

This is a review bogged down in a back-and-forth of comments and revisions. Code reviews are not meant as a podium for discussions. The goal is to improve the resulting product and not to find out who has the better arguments. Giving references and examples or involving a third party can help when a discussion drifts into a debate.

Overdoing it

The goal of a code review is not about figuring out the best code possible. Code does not need to be perfect to be functional and maintainable. Perfectionism sometimes gets in the way and can slow development or even introduce bugs by trying to overdo it, such as premature optimization.

Underdoing it

Approving code reviews as a formality, skipping over important aspects of the code, or performing a superficial review can result in missed issues or potential improvements. A thorough review is necessary to ensure that the code is high quality and meets all necessary requirements.

What Does a Good Code Review Look Like?

Clear Goals and Expectations

It is important to establish clear goals and expectations for the code review to ensure that it is focused and efficient. This includes understanding the purpose of the code and the requirements it needs to meet, and any guidelines or standards that need to be followed.

Thorough Review

A good code review should be thorough, covering all aspects of the code to ensure that it is high quality and meets all necessary requirements. This involves looking at the code, testing it, and checking for potential issues or improvements. Some things to consider when reviewing code include:

1. Functionality: Does the code do what it is supposed to do? Is it complete and correct?

2. Performance: Is the code efficient and well-optimized? Are there any bottlenecks or potential performance issues?

3. Security: Does the code follow best practices for security? Are there any potential vulnerabilities that need to be addressed?

4. Maintainability: Is the code easy to understand and maintain? Are there any areas where the code could be refactored or simplified?

Constructive feedback

Feedback during a code review should be constructive, focused on helping the developer improve their code rather than simply pointing out flaws. This involves explaining the reasons behind any suggestions or recommendations and providing alternative solutions where appropriate. It is important to be respectful and professional in code reviews, as the goal is to improve the code, not to criticize the developer.

Efficient Process

A good code review should be an efficient process, taking into account the time and resources available to the team. This involves setting clear deadlines for the review and ensuring that the review process is streamlined and does not hold up the development process. It's important to balance the need for thoroughness with the need to be efficient and not hold up the development process.

Collaborative approach:

A good code review should involve open communication and collaboration between the developer and the reviewer. This involves asking questions, seeking clarification, and working together to resolve any issues.

It is important to foster a culture of collaboration and mutual support in code reviews, as this can help to improve the overall quality of the codebase and the development process.

Code Review Best Practices

As a code author:

• Short and isolated code reviews. Since long code reviews can be overwhelming and difficult to complete, keeping them short makes it easier for reviewers to stay focused and provide more thorough and accurate feedback.

• Leave a good description of the code review so that the people reviewing it can understand what you are solving.

• Automate menial tasks like code style checks and linting. Anything that can be automated should not be part of the code review.

• Being specific to a feature/bug makes it easier to identify and address issues more quickly, rather than reviewing code that is unrelated to the feature or bug in question.

• Answer & resolve all feedback, even if it's not actionable. Even if a comment is not actionable, it might still be based on a misunderstanding or incorrect assumption that can be clarified. Also, it shows respect for the reviewer and can help maintain a positive and productive working relationship.

• Be an egoless developer. Developers need a robust enough ego to trust and defend their work but not so much ego that they reject suggestions for better solutions. Similarly, the egoless reviewer should have compassion and sensitivity for their colleagues, if only because their roles will be reversed one day.

• Let everyone participate. Code reviews are not only limited to experienced developers. Junior developers should also partake in these discussions since it is an opportunity for them to learn from more experienced developers. Also, code reviews act as a great knowledge transfer session for the whole team to learn more about the overall codebase, architecture, etc.

As a code reviewer:

• Understand the purpose of the code review: Before starting the review, make sure you understand the code review's purpose and the code changes' goals. This may involve reading the PR description and any relevant documentation and reviewing the code changes themselves.

• Leave clear and specific feedback (overcommunicate as possible), explain the reasoning behind your requested changes, and provide solutions when possible. Also, make sure to give credit to the author for aspects of the code that is well done.

• Ask questions instead of demanding changes. Asking questions allows others to share their thoughts and insights instead of demanding changes that can come across as confrontational. So for example, instead of saying Recursion should be used here, you can say What do you think about using recursion here? It can help the author to reflect and think about your input without getting defensive.

• Rephrase feedback as your own opinion andavoid stating them as universal facts. For example, It's hard for me to understand this logic instead of This logic is hard to understand makes it less likely that the author gets defensive and disagrees with your perspective, thus creating more willingness to look for solutions

• Do not jump to conclusions. Make sure to communicate any concerns or questions you may have.

• Promote team ownership. Consider approval as becoming a co-author of the change.

• Concentrate your comments on the scope of change. Raise other changes separately as technical debt.

• Review in a timely manner.

• Take conversations offline instead of long discussions on the code review. Sometimes by doing so, it's possible to have more focused and productive conversations.

Conclusion

Code review is an essential part of the software development process. Good code reviews are clear, thorough, constructive, and efficient. However, issues like nitpicking, ongoing debates, and perfectionism can undermine the process. 

Code Authors: Remember to keep your reviews short and specific, automate tasks, and check your ego at the door.

Code Reviewers: Ensure you understand the purpose of the review, provide clear and specific feedback, and review promptly.

When everyone does their part and respects the process, code reviews can be the most valuable stage in your software development process. 

More Questions?

Check out our post on creating an efficient code review process, or schedule a free consultation call to pick our brains!