Code review is all about authors inviting other developers to give their input on the code before it becomes part of our codebase. It’s more than just spotting errors; it’s a team effort to make our code even better, share knowledge, and uphold coding standards together.

Code review Benefits

Enhanced code quality: Code reviews play a vital role in enhancing the overall quality of the code. They pinpoint bugs, performance issues, security vulnerabilities, and other flaws early on in the development process.

Sharing knowledge: Through code reviews, team members can learn from one another, gaining deeper insights into the codebase and coding standards.

Consistency: Code reviews ensure that coding standards and best practices are consistently applied throughout the project.

Team collaboration: Code reviews create a supportive atmosphere, enhancing teamwork and trust within the team.

Continuous improvement: By offering feedback and pinpointing areas for improvement, code reviews help developers enhance their coding skills and refine their practices.

Code review Drawbacks

Time-consuming: Code reviews can be time-consuming, especially for large codebases or complex projects.

Development delays: Code reviews might cause a bit of a delay in the development process since developers might have to wait for their code to be reviewed before moving forward.

Feedback overload: Code reviews might give developers a lot of feedback, which makes it challenging for them to handle.

Reviewer quality: The feedback and code review quality can vary depending on how much experience and knowledge the reviewers have.

Resistance to feedback: Developers may resist feedback or suggestions from reviewers, which could lead to conflicts and delays in progress.

Code review Best Practices

The code review process involves different perspectives: the code author, who asks for feedback, and the code reviewers, who look through the code change and provide feedback. While some best practices are specific to authors or reviewers, many benefit everyone on the team.

Today, we’ll talk about code review best practices which primarily focus on GitHub and pull request (PR) reviews, but with tips applicable across the board.

1. Things that matter:

To keep things friendly and productive during code reviews, it’s helpful to have some guidelines in place. Here’s what we suggest focusing on:

• Design: Is the code nicely designed and suitable for your system?
• Functionality: Does the code work as expected by the author? Does it benefit its users?
• Complexity: Can the code be simplified? Will other developers find it easy to understand and utilize in the future?
• Tests: Are there proper and well-constructed automated tests for the code?
• Naming: Did the developer choose clear names for variables, classes, methods, etc.?
• Comments: Are the comments clear and useful?
• Style: Does the code follow our style guides?
• Documentation: Did the developer also update relevant documentation?

It’s best for developers not to spend their time reviewing things that can be automatically checked.

2. Discuss the high-level approach early

Before delving into coding a complex feature, it’s good to chat about the big picture first. Usually, we do this when we’re planning out the feature.

It’s not very pleasant if a PR needs a complete overhaul because we didn’t discuss the approach beforehand. PR rewrites do happen every so often, but it’s a hint that we should have a more thorough chat before diving in.

Sometimes, to get things rolling, we need a proof-of-concept. A great way to start is by opening a draft PR of the approach and making architectural decisions based on what we learn.

3. Use code review checklists

Using a code review checklist helps ensure consistency among all team members involved in coding or reviewing. It supports both seasoned developers and newcomers by providing guidance on best practices for their language or framework.

50% of the companies spend 2–5 hours weekly on code reviews. You can streamline this process with a checklist, and developers save time.

4. Keep pull requests small

Breaking down tasks into smaller batches makes them more manageable and efficient to handle. It’s essential to consider not only the number of lines but also the number of files affected by the change.

Concentrating on smaller sections allows reviewers to thoroughly inspect all aspects (Consider using a code review checklist). With smaller PRs, developers can quickly understand code changes, and reviewers can give more focused and detailed feedback. This approach ensures that each change gets the attention it deserves and makes it easier to follow the style guide.

5. Foster a positive feedback culture

The code review process should be viewed as a chance for growth and knowledge exchange, rather than a critique of developers’ capabilities.

For successful code reviews, it’s crucial to establish a culture of collaboration and learning. Below is a list of suggestions for improving code review discussions:

• Always provide feedback on the code, not the author.
• Be open to the suggested changes.
• Inform those who benefit from this review.
• Admit that there are multiple correct solutions to every problem.
• Provide positive and helpful feedback.

This allows the development team to know the purpose behind code review and take it as a way to improve their coding abilities and skills.

6. Automate as much as possible

Code review is important, but it’s time-consuming. Therefore, it is advisable to automate tasks that can be automated.

Use GitHub Actions for building a robust CI pipeline. Automated checks free up reviewers to concentrate on significant areas. it helps improve the code quality and increase the level of speed, precision, and consistency.

With GitHub Actions, developers can save time and avoid the frustration of having to manually check the quality. The action automatically gathers and organizes all the relevant tests, test coverage, code style checks, commit message standards, static analysis, and much more.

7. Do less nit-picking

Your role as a reviewer is to assist with fundamental concerns like bugs, architectural issues, code design, or anything affecting maintainability. If you find yourself focusing too much on minor details, think about automating those checks to save time.

many of the things that are nitpicked in code reviews can be caught by using ESLint rules or Prettier to help identify issues such as syntax errors, unused variables, formatting, and other common mistakes that developers make. By automating these checks, we can free up time for code reviewers to focus on the bigger picture, such as the design of the code, the overall architecture, and the test coverage.

8. Automate review requests:

When collaborating on large projects with multiple developers and numerous pull requests (PRs) being generated simultaneously, it can become challenging for reviewers to keep track of each PR. Sometimes, during the feedback loop, reviewers may not be aware if the author has made changes or not. In such situations, we require a mechanism to notify the code owner, ensuring that the feedback changes are ready for review.

In these situations, using GitHub’s review requests is a friendly and helpful way to inform others that your code is prepared for review.

9. Read through your changes

Before submitting a PR for review, it’s best to carefully review your code changes. It’s important to ensure you’ve addressed any issues yourself before asking others for feedback. This saves reviewers time and helps you catch any overlooked changes or issues that need fixing.

10. Document code review decisions

For a coder, having reliable documentation is really important. Good documentation helps us understand the functionality of the code, promotes maintainability, and ensures seamless collaboration within our development team.

• Documentation helps us understand the purpose and intent of the code.
• Comments and README files make it easier for everyone to understand.
• Well-documented code makes maintenance easier.
• Clear explanations help solve problems quickly.
• Documentation speeds up the onboarding process for new team members.
• It offers insights into code structure and functions.
• Documentation ensures we follow coding standards.
• It keeps things consistent across the codebase.

11. Create a clear PR title and description

One great thing to do during code review is to write a description of what this code change is all about. This helps reviewers understand the purpose of the change and why you made it. Following this practice can speed up review time, improve feedback quality, and increase participation rates.

Feel free to include extra details in your PR description, such as your JIRA ticket link. Adding a visual demo is a nice touch too. You can use a screenshot, a screen capture, terminal output in a code block, or anything else that effectively shows the change. GitHub allows videos and GIFs in PR descriptions.

12. Ask open-ended questions

Asking questions is the best way of learning. Open-ended questions encourage the author to reflect critically and autonomously on their code. By asking open-ended questions, you might discover something new, rather than presuming you understand the context behind the author’s code.

If you found it enjoyable and helpful, please don’t hesitate to give me a couple of claps! 👏