GitHub Code Review Best Practices

Contributing code to projects hosted on GitHub can be a great way to leverage distributed development processes and a remote working paradigm to the fullest. But what happens when your code contributions need to pass a sniff test before they make it into the main codebase? That's precisely where reviews come into the picture, and getting them right can make a world of difference for your project.

Why code review matters

Reviewing code may seem like an onerous and unnecessary task worth skipping out on, but it’s often one of the most critical facets of the development process. Without proper code reviews taking place whenever new code is contributed to a given project, any number of vulnerabilities can be introduced into the code base—and they’re sure to crop up as ongoing issues that will need to be solved later on.

Problematic code can take on many forms, and something as simple as a unique indentation style in one contributor's code can cause headaches and conundrums for other team members (ditto if the language used features indentation-based statement grouping, like Python). Even when minor inconsistencies are not immediate threats to your project's security, they can still cause problems.

As your code base grows and the many contributions from different team members come together, stylistic differences can take a toll on productivity. If developers use different coding patterns on a single project, they’re likely to eventually be confronted with a pattern they’re not accustomed to; they must then learn to work it with before they can handle any changes or additions they intend to create. This issue can balloon into a show-stopping problem that effectively cripples development momentum and needlessly frustrates your team.

Code review addresses the issues above (and more) by adding a cautionary step between code development and deployment. On GitHub, this step is normally best positioned after each pull request, but there’s plenty to consider when implementing a code review process there before jumping in.

Code review on GitHub

On GitHub, code review is integral to the standard GitHub flow, coming into effect right after each pull request. Although specific approaches to review handling may vary across teams, it’s generally encouraged for there to be at least one proper check before code is merged into your primary repository.

In the case of repositories with integrated CI/CD (continuous integration, delivery, and deployment) processes, standardized portions of each code review are automated to free up developers' time and energy. However, even with manual code reviews being the only ones used for a given project, time-saving options exist for developers to leverage in GitHub, such as linking pull requests to existing issues and mentioning specific user accounts so that they will be notified when the request is submitted.

Reviewers on GitHub can engage with pull requests in multiple ways to help guide contributors through the process of having their work accepted for merging into the main branch. Here are a few things that reviewers can do with new pull requests once they have begun reviewing them:

• Adding comments: Reviewers can add information to pull requests in the form of comments to instruct contributors on how to get approval for the changes they’ve worked on. Comments can be added to each line of code that a reviewer finds important or simply to the entire pull request. Code suggestions and images can be used to illustrate your points this way as well.

• Approving changes: Once a reviewer has gone over the changes presented by a pull request and found them to be safe for a final merge into the main branch, they can approve the request. Suppose multiple approvals are required for a pull request to be merged. In that case, special logic for stale review dismissal can be activated to ensure pull requests can be merged by administrators in a hurry, even if they have not been reviewed again since additional changes were made.

Code review best practices

The best practices below should give you a good idea of where to start with your code reviews and what you can do to improve them:

Cover essential issues

Setting up a checklist that covers recurring concerns and ensuring all reviewers stick to it makes maintaining review quality quite a bit easier. Here are a few items that should make an appearance on such a list:

• Code readability and style: Consistent coding style is important, and readability is equally so. Great code readability ensures other team members can keep up with each contribution that’s merged into the main repository without having to ask around for information on how pieces of the codebase actually work.
• Code patterns: The design patterns that your project uses should be consistent and easy to reason about. This accelerates the learning curve involved in team members getting up to speed with existing components as they work.

Limit review time

Reviewing code can be challenging, often requiring a surprising degree of concentration to be handled effectively. Setting time limits for reviews helps keep reviewers from missing important details. Whether they should simply take a break and return to finish their review or pass on remaining code to another reviewer is up to you.

Automate wherever possible

CI/CD processes were briefly mentioned above and for good reason—they can be tremendously powerful for improving productivity. However, there are many facets of CI/CD that your team can leverage at a given time.

From CI's integrated unit tests to CD's multifaceted deployment potential, automation can quickly take over the most tedious aspects of your development pipeline. Mergify meshes well with this important tenet of code reviewing by providing ways to refine your workflow further.

Mergify makes code review faster 🥰

Although many CI/CD tools can perform the types of tests and configurations needed to get code from point A to point B safely, Mergify can help take them one step further with automated merging after CI tests have concluded and more. To learn about how Mergify can help improve your code review process, sign up for a demo today.