:wq cheats/code-review
Tags: awesome, cheatsheets, bestpractices, codereview
Published: 2023-09-13 19:36:36

## The One About Code Reviews

_TL;RD_

*Some best practices for getting great Code Reviews*

  - Keeping the Pull Request small and focused on a single feature or bug fix
  - Providing clear and concise descriptions of the changes made
  - Including relevant documentation and tests
  - Addressing any known issues or potential concerns in the description
  - Requesting specific feedback or areas of review from the reviewers
  - Being responsive and open to feedback during the review process
  - Making changes and updates based on the feedback received
  - Keeping the Pull Request up-to-date with the latest changes in the codebase.

*Some best practices for giving great Code Reviews*

  - Setting clear expectations for the review process
  - Focusing on the code, not the person who wrote it
  - Providing specific, actionable feedback
  - Being respectful and constructive in your comments
  - Prioritizing high-impact issues over minor ones
  - Following up on the review to ensure that feedback is addressed
  - Encouraging collaboration and discussion among team members.

*Some common mistakes to avoid*

  - Making the review personal or attacking the author
  - Focusing on minor issues at the expense of larger ones
  - Being too nitpicky or pedantic
  - Not providing enough context or explanation for your feedback
  - Not following up on the review to ensure that feedback is addressed
  - Not being open to feedback yourself
  - Not considering the bigger picture or the project's goals.

___

### My Favorite Resources on Code Reviews

Curated list of tools, articles, books, and any other resource related to code review

___

**Pull Requests, Code Review, and the GitHub Flow** • [GitHub Universe 2015][3]

> Discusses the benefits of using the GitHub Flow for development. GitHub Flow helps to promote collaboration, code review, and continuous delivery.

- **What are pull requests?** 
  
    Pull requests are a way to propose changes to a codebase and get them reviewed by other developers.
    They are a key part of the GitHub Flow, a development workflow that emphasizes collaboration and code review.

- **Why are pull requests important?** 
  
    Pull requests help to ensure that code is of high quality and that it meets the team's standards. 
    They also help to promote collaboration and knowledge sharing among developers.

- **How to create a good pull request**

  - Write a clear and concise description of your changes.
  - Make sure your changes are small and focused.
  - Test your changes thoroughly before submitting your pull request.
  - Be responsive to feedback from reviewers.

- **How to review a pull request**
  - Take the time to read and understand the changes.
  - Test the changes yourself.
  - Provide constructive feedback to the developer.
  - Be respectful of the developer's time.

- **Here are some additional key takeaways from the talk:**
  
  - Pull requests should be used for all changes to the codebase, no matter how small.
  - Code reviews should be focused on the overall quality of the code, not just on finding bugs.
  - It is important to be respectful of the developer's time when providing feedback on a pull request.
  - The GitHub Flow is a great development workflow for teams of all sizes.

___

**Code Review is an Architectural Necessity** • [GitHub Universe 2016][4]

> Emphasizes the importance of making code review a regular part of the development process. Code review should be seen as an investment in the quality and maintainability of the software system.

- **Code review is an architectural necessity because it helps to ensure that code is:**

  - **Correct:** Code review helps to catch bugs and errors in code before it is deployed to production.

    - **Consistent:** Code review helps to ensure that code is written in a consistent style and that it follows the team's coding standards.

    - **Maintainable:** Code review helps to ensure that code is easy to read and understand, making it easier to maintain in the future.

    - **Secure:** Code review can help to identify and fix security vulnerabilities in code.

- **Code review can also help to improve the overall architecture of a software system by:**

    - **Identifying and refactoring potential architectural flaws:** Code review can help to identify areas of the code that are poorly designed or that could be improved.

    - **Ensuring that the code is aligned with the overall architectural vision for the system:** Code review can help to ensure that the code is being written in a way that is consistent with the team's overall architectural vision for the system.

- **Tips for effective code review:**

    - **Set clear expectations for code reviews:** The team should have a clear understanding of what is expected of code reviews, such as what types of issues should be raised and how the reviews should be conducted.

    - **Use a code review tool:** A code review tool can help to streamline the code review process and make it more efficient.

    - **Be constructive in your feedback:** Code reviewers should focus on providing constructive feedback that will help the developer improve their code.

    - **Be respectful of the developer's time:** Code reviews should be conducted in a timely manner, and reviewers should be respectful of the developer's time.

___

**Implementing a Strong Code-Review Culture** • [RailsConf 2015][5]

> Code reviews are not about catching bugs. 
> Modern code reviews are about socialization, learning, and teaching.

- **The primary purpose of code review:** Improve the overall code health of the system being worked on, not to catch bugs or enforce style guides.

- **Reviewers should favor approving a change, even if the change isn’t perfect:** Once it is in a state where it definitely improves the overall code health of the system.

- **Reviewers should balance out:** The need to make forward progress compared to the importance of the changes they are suggesting.

- **Reviewers should also mentor developers:** By teaching them something new about a language, a framework, or general software design principles.

- **Reviewers should not require the author to polish every tiny piece of a change before granting approval:** But they should feel free to leave comments expressing that something could be better, prefixed with something like `"Nit: "` to let the author know that it’s just a point of polish that they could choose to ignore.

- **Reviewing code and writing easily-reviewed features are skills:** That will make developers better and more productive teammates.

___

**Goldilocks And The Three Code Reviews** • [JSConf Budapest 2017][6]

> Encourages developers to be supportive of each other and to learn from each other's code

### The three types of code reviews

- **Too short:** This type of review is too focused on finding bugs, and it doesn't give enough feedback on the overall quality of the code.

- **Too long:** This type of review is too nitpicky, and it can discourage developers from submitting their code for review.

- **Just right:** This type of review is focused on finding bugs and improving the overall quality of the code, but it is also respectful of the developer's time and effort.

### How to write a good code review

- Focus on the overall quality of the code, not just on finding bugs.

- Be constructive and specific in your feedback.

- Be respectful of the developer's time and effort.

### How to get the most out of code reviews

- Be open to feedback and suggestions.

- Be willing to make changes to your code.

- Ask questions if you don't understand something.

___

**The Science of Code Reviews** • [DPC2018][9]

> Code reviews should be seen as an opportunity to learn and grow, not as a way to criticize or blame developers

- **Code reviews are an important part of the software development process:** They help to improve the quality of the code by identifying and fixing bugs, improving the overall design of the code, and ensuring that the code follows the team's coding standards.

- **However, code reviews can be time-consuming and inefficient:** It can be difficult to know which parts of the code to focus on, and it can be challenging to provide constructive feedback.

- **Research on code reviews has shown that there are a number of factors that can affect the effectiveness of code reviews. These factors include:**

    - The size and complexity of the code being reviewed.
    - The experience and expertise of the reviewers.
    - The process used for the code review.

### Based on this research, Kuipers recommends a number of best practices for code reviews

- **Focus on the most important parts of the code:** Not all code is created equal. Some parts of the code are more important than others, and they should be the focus of the code review.

- **Use a code review tool:** A code review tool can help to automate tasks such as identifying potential bugs and code violations. This can save time and effort, and it can help to improve the quality of the code review.

- **Provide constructive feedback:** The goal of a code review is to improve the code, not to criticize the developer. Feedback should be specific and actionable, and it should be delivered in a respectful and constructive manner.

___

**Code Reviews: Honesty, Kindness, Inspiration: Pick Three by Jacob Stoebel** • [RubyConf 2017][10]

> Introduces the **Liz Lerman Critical Response** process for code reviews. Encouraging to try out this process and see how it can improve their code reviews and their team culture

- **Code reviews can be both honest and nice:** While code reviews should be both honest and kind, they should be focused on inspiring creators to go back to their work, excited to make it better. 

- **The Liz Lerman Critical Response process consists of:**

    - #1. statement of meaning
    - #2. artist questions
    - #3. neutral questions
    - #4. permissioned opinions

___

**Amazing Code Reviews: Creating a Superhero Collective** • [GOTO 2019][17]

> Many code reviews are superficial, unclear, or unhelpful, which can lead to frustration, wasted time, and missed opportunities
> Code reviews are an important step for improving the code health, quality, and knowledge of the system being worked on
> How to create a culture of amazing code reviews in software development teams

### Key principles and practices of Shopify's code review process

- Focus on the **intent** of the change, not the **implementation**
- Provide **actionable feedback** that helps the author improve their code and learn something new
- Use **positive language** and **empathy** to communicate their feedback in a respectful and constructive way
- **Trust** the author to make the final decision on their change
- **Celebrate** the author's work and achievements

### Benefits and challenges of this code review process, such as:

- Increases the **collaboration**, **learning**, and **motivation** of the team
- Improves the **consistency**, **readability**, and **maintainability** of the code base
- Requires more **time**, **effort**, and **skill** from both reviewers and authors
- Depends on the **context**, **culture**, and **preferences** of the team

___

**Creating Simple and Effective Guidelines for Code Reviews** • [@newrelic][11]

> Simple and effective code review guidelines that will help them to improve the quality of their code

- **Clear, concise, and easy to understand** 
  
    They should be written in a way that is accessible to both experienced and inexperienced developers.

- **Tailored to the specific needs of the team and the project** 

    The guidelines should take into account the type of code being reviewed, the experience level of the reviewers, and the goals of the code review.

- **Focused on the quality of the code, not on the individual developer** 

    The guidelines should be used to identify and fix bugs, improve the overall design of the code, and ensure that the code follows the team's coding standards.

- **Updated regularly**

    To reflect the team's changing needs and practices

### Recommendations for code review guidelines

- **Identifying and fixing bugs**

  - Look for common bugs such as missing semicolons, unending loops, and missing error handling.
  - Be aware of the team's coding standards and ensure that the code follows them.
  - Test the code yourself to see if it works as expected.

- **Improving the overall design of the code**

  - Look for areas where the code can be simplified or refactored.
  - Suggest ways to make the code more readable and maintainable.
  - Consider the overall architecture of the system and ensure that the code fits well within it.

- **Ensuring that the code follows the team's coding standards**

  - Look for areas where the code does not follow the team's coding standards.
  - Suggest ways to make the code more consistent with the team's standards.
  - Be aware of any new coding standards that have been adopted by the team.

___

**Code Review As A Gateway** • [@jetbrains][12]

> Overall, code review as a gateway is a valuable process that can help to improve the quality of code, reduce the risk of regressions, and improve collaboration between developers.

- **Code review as a gateway is a process where a code review is required before any code is merged into the main branch.**

    This process can help to ensure that the code is of high quality and that it meets the team's standards.

### There are a number of benefits to using code review as a gateway

- **Improved code quality** 
  
    Code reviews can help to identify and fix bugs in the code, improve the overall design of the code, and ensure that the code follows the team's coding standards.

- **Reduced risk of regressions** 

    Code reviews can help to prevent regressions by ensuring that new code does not break existing functionality.

- **Improved collaboration** 

    Code reviews can help to improve collaboration between developers by providing a forum for developers to discuss their code and learn from each other.

### There are a few things to keep in mind when implementing code review as a gateway:

- **Setting clear expectations** 

    It is important to set clear expectations for code reviews, such as what types of issues should be raised and how the reviews should be conducted.

- **Providing training** 
  
    It is important to provide training to developers on how to conduct effective code reviews.

- **Using a code review tool** 
  
    A code review tool can help to automate tasks such as identifying potential bugs and code violations. This can save time and effort, and it can help to improve the quality of the code review.

- **Being flexible** 
  
    It is important to be flexible when implementing code review as a gateway. There may be cases where it makes sense to bypass the code review process, such as for small changes or for changes that are made by experienced developers.

___

**How to Do Code Reviews Like a Human (Part One)** • [@mtlynch.io][13]

> Emphasizes the importance of having a `"blameless culture"` when it comes to code review. 

### Focus on finding and fixing bugs, not on blaming the developer who wrote the code.

  - Code review is a process in which one or more developers review the code of another developer.

  - Code review can help to improve the quality of the code by identifying and fixing bugs, improving the overall design of the code, and ensuring that the code follows the team's coding standards.

  - To be effective, code reviews should be conducted in a collaborative and respectful manner.

### Here are some tips for doing code reviews like a human:

- **Set clear expectations for the code review** 

    This includes things like what types of issues should be raised and how the reviews should be conducted.

- **Be prepared for the code review** 

    This means taking the time to read and understand the code before the review begins.

- **Be specific and constructive in your feedback** 
  
    Focus on providing feedback that will help the developer improve their code.

- **Be respectful of the developer's time**. 

    Code reviews should be conducted in a timely manner, and reviewers should be respectful of the developer's time.

___

**How to Do Code Reviews Like a Human (Part Two)** • [@mtlynch.io][14]

> Emphasizes the importance of creating a positive and supportive culture for code reviews. Code reviews should be seen as an opportunity to learn and grow, not as a way to criticize or blame developers.

### How to handle disagreements in code reviews

- **Be respectful and open-minded**

    Even if you disagree with a developer's code, it's important to be respectful of their work and to be open to their perspective.

- **Try to understand the developer's motivation**

    Why did they write the code in the way that they did? Once you understand their motivation, you can better understand their reasoning and you may be able to find a compromise.

- **Be willing to compromise**

    It's important to be willing to compromise in code reviews. Not every change that you suggest will be accepted, and that's okay.

- **Don't be afraid to escalate the issue** 

  If you can't come to an agreement with a developer, you may need to escalate the issue to a more senior developer or to a manager.

### How to give effective feedback in code reviews

- **Be specific and actionable** 

    Don't just say `"This code is bad."` Explain why you think the code is bad and suggest a specific way to fix it.

- **Be positive and constructive** 

    Focus on providing feedback that will help the developer improve their code. Avoid being negative or critical.

- **Be concise and to the point** 

    Don't overwhelm the developer with a lot of feedback. Focus on the most important issues.

- **Be open to feedback yourself** 

    It's important to be open to feedback from other developers, even if you don't agree with it.

### How to get the most out of code reviews

- **Be open to feedback** 

    Be willing to listen to feedback from other developers and to make changes to your code based on their feedback.

- **Be prepared for the code review** 

    Take the time to read and understand the code before the review begins.

- **Be responsive to feedback** 

    If a developer raises an issue with your code, try to address it promptly.

- **Ask questions**

    If you don't understand something in the code, ask questions.

___

**How to Give and Get Better Code Reviews** • [@medium][15]

> Emphasizes the importance of creating a culture of `"trust"` and `"respect"` in order to foster effective code reviews. 
> Encourages developers to be supportive of each other and to learn from each other's code.

- **How to give better code reviews:**

  - Try to understand the context and the proposed solution.
  - Be specific and actionable in your feedback.
  - Focus on the overall quality of the code, not just on finding bugs.
  - Be respectful of the developer's time and effort.

- **How to get the most out of code reviews:**

  - Be open to feedback and suggestions.
  - Be willing to make changes to your code.
  - Ask questions if you don't understand something.

- **Additional tips:**

  - Set clear expectations for code reviews.
  - Use a code review tool.
  - Be constructive in your feedback.
  - Be respectful of the developer's time.
  - Make code review a regular part of the development process.

___

## REFERENCES

- [What to Look for in a Code Review: A Guide for the Reviewer][1]
- [A curated list of tools, articles, books, and any other resource related to code review][2]
- [Pull Requests, Code Review, and the GitHub Flow - GitHub Universe 2015][3]
- [Code Review is an Architectural Necessity - GitHub Universe 2016][4]
- [RailsConf 2015 - Implementing a Strong Code-Review Culture][5]
- [Vaidehi Joshi: Goldilocks And The Three Code Reviews | JSConf Budapest 2017][6]
- [DPC2018: The Science of Code Reviews - Rick Kuipers][9]
- [RubyConf 2017: Code Reviews: Honesty, Kindness, Inspiration: Pick Three by Jacob Stoebel][10]
- [Creating Simple and Effective Guidelines for Code Reviews][11]
- [Code Review As A Gateway][12]
- [How to Do Code Reviews Like a Human (Part One)][13]
- [How to Do Code Reviews Like a Human (Part Two)][14]
- [How to Give and Get Better Code Reviews][15]
- [Amazing Code Reviews: Creating a Superhero Collective][17]
- [Sane Code Reviews: A guide to improve the Git(Hub) flow and commits messages • @roalcantara][16]

[1]: https://leanpub.com/whattolookforinacodereview "What to Look for in a Code Review: A Guide for the Reviewer"
[2]: https://project-awesome.org/joho/awesome-code-review "A curated list of tools, articles, books, and any other resource related to code review"
[3]: https://youtu.be/vCwuZfK0VG4 "Pull Requests, Code Review, and the GitHub Flow - GitHub Universe 2015"
[4]: https://youtu.be/pJFM321_lAs "Code Review is an Architectural Necessity - GitHub Universe 2016"
[5]: https://youtu.be/PJjmw9TRB7s "RailsConf 2015 - Implementing a Strong Code-Review Culture"
[6]: https://youtu.be/d2CMwgm2pXk "Vaidehi Joshi: Goldilocks And The Three Code Reviews | JSConf Budapest 2017"
[9]: https://youtu.be/pL_fJ2fQSZw "DPC2018: The Science of Code Reviews - Rick Kuipers"
[10]: https://youtu.be/hP_2XKYia9I "RubyConf 2017: Code Reviews: Honesty, Kindness, Inspiration: Pick Three by Jacob Stoebel"
[11]: https://newrelic.com/blog/best-practices/code-review-guidelines "Creating Simple and Effective Guidelines for Code Reviews"
[12]: https://blog.jetbrains.com/upsource/2017/01/18/code-review-as-a-gateway "Code Review As A Gateway"
[13]: https://mtlynch.io/human-code-reviews-1 "How to Do Code Reviews Like a Human (Part One)"
[14]: https://mtlynch.io/human-code-reviews-2 "How to Do Code Reviews Like a Human (Part Two)"
[15]: https://medium.com/hackernoon/how-to-give-and-get-better-code-reviews-e011c3cda55e "How to Give and Get Better Code Reviews"
[16]: https://github.com/roalcantara/sane-code.reviews "Sane Code Reviews: A guide to improve the Git(Hub) flow and commits messages"
[17]: https://youtu.be/ly86Wq_E18o "Amazing Code Reviews: Creating a Superhero Collective"