6 Concrete Tips That Will Make Your React Pull Requests Easier To Review

Reviewing is a core process in software development and can be one of the most valuable aspects for an engineering team. If it’s done correctly, it can have a significant positive impact on the team’s communication, quality of the codebase, and the stability of the features put out by the engineering team.

However, not every pull request is equally easy to review. The harder it is to review a pull request, the more difficult it is for the reviewer to provide high-quality reviews. As a code proposer, you can help with this process by making sure that your pull requests are as easy to review as possible.

In the end, this entire process is a team effort. In that context, optimising their end of the workflow is also part of your job as a colleague. But how do you make your React pull requests easier to review for your colleagues?

Based on personal experience, this article will cover 6 concrete and actionable improvements you can make to your React pull requests that will make them easier to review. In turn, this will set up your reviewers for success, allow you to receive more meaningful reviews from your colleagues, prevent unnecessary discussions, and in general optimize the review process inside the team.

Include The Purpose Of The Pull Request

Every pull request introduces code changes with a purpose, a reason, and context. For React pull requests, there is a very large list of reasons to introduce code changes. The changes could be HTML related, for visual purposes (CSS), JavaScript related, to fix a bug, for client-side, for server-side rendering, for unit tests, for end-to-end tests, for rendering performance, and the list goes on.

Without the purpose of the pull request, it’s extremely hard or even impossible for other developers to properly review your code. It’s like asking your colleagues to verify whether a car is working properly without telling them why the car was necessary and only showing them the car.

Over the past years, I’ve experienced a lot of pull requests where the purpose was left out. Either one of my colleagues left it out and I was the code reviewer or I was the code proposer. Most of the time, the code proposer thought that the pull request was clear enough on its own, too small to warrant such information, was just too lazy, forgot about it, or thought it was unnecessary. But in all cases, it made reviewing for the other colleague very difficult and required additional communication, back-and-forths, and more wasted time across the engineering team.

Every pull request introduces code changes with a reason. Without that reason, any code change would be meaningless and make it difficult for the reviewer to perform a proper review of your work. That’s why it’s extremely important to include the purpose of the pull request inside of it. The purpose of the code changes is what provides the reviewer with a foundational layer to understand your code and what they need to deliver meaningful code reviews.

Including the purpose of the pull requests doesn’t require a lot of effort. A simple one-liner or small comment in the pull request can already be enough for your reviewer. However, the drawbacks to not doing it are extremely significant. Leaving out the purpose of the pull request handicaps your colleagues from doing their job properly and will waste time and effort from everyone involved.

Share Screenshots Of Visual Changes

As React developers, any code that we touch is most of the time related to the frontend part of an application. It is what end-users use, see, and interact with. This is the part of the application that stands closest to your end-users and any changes to it will directly affect the experience of the end-user.

Thus, a large portion of our responsibilities as frontend developers is implementing the visual appearance of the application. You could be using CSS, CSS in JS, Sass, or any other form of styling for your web application. In the end, it all boils down to the same thing, namely that you’re making visual changes that will appear to the end-user.

Unfortunately, it’s extremely difficult to imagine visual changes based on only the code changes themselves. Going from CSS styles to the actual visual changes is not a trivial task, but it’s basically what reviewers have to do.

During my three years of work experience as a React developer, I’ve rarely seen someone review a pull request containing styling changes and immediately understanding what the results were. I’ve so often contacted the code proposer to show me what their code changes reflected visually. In the end, the result was the same: they showed me a screenshot and I could understand.

But all of this back-and-forth could’ve been avoided if they included those screenshots directly into the pull request. Visual changes are extremely hard to imagine based on code alone, but a single screenshot can already make a world of difference for your reviewer. It requires little effort but yields so many benefits for your reviewer, you, and the team.

Provide Feature Requirements

Every feature that gets implemented has a set of requirements on how it should work and behave. Most of the time, these expectations come from customers and the product manager. But it’s also possible that there are requirements on a technical level, like requiring certain props, function arguments, certain usage, or structure of data. So requirements can also come from developers.

Without these requirements, it’s difficult for code reviewers to determine whether the code that you’re proposing is good or not. This is very similar to leaving out the purpose of a pull request, but then for individual blocks of code. A small piece of code that looks very weird can be necessary to satisfy a certain requirement. But without the contextual information, it’s just a weird piece of code.

Providing the feature requirements can be done in a lot of different ways and depends on different factors. The most straightforward one is writing them out in the pull request for your reviewers, but that is very time consuming and not a great long-term solution. If the requirements were already documented when provided to you, then including that document in the pull request doesn’t require a lot of effort. The problem is that those documents will be hard to trace down for future developers when they’re going through the code. Requirements can also be documented in tests which is the most future-proof solution but does require a lot more implementation effort from the proposer.

Elaborate On New Dependencies

In the world of frontend and React development, there is a lot already discovered, created, and available to use. Creating something from scratch oftentimes means that you’re reinventing the wheel, which can be a suboptimal allocation of time, effort, and resources. To prevent this, it’s common to tend towards existing solutions and use existing libraries.

However, picking a particular NPM library from the available dozens is not always a trivial decision. There are a lot of factors to consider, like the bundle size, your use cases, how well it’s maintained, the copyright license, whether it integrates easily into your codebase, how bloated it is, whether it’s easy to use, whether it provides typings out of the box, how it compares to alternatives, and much more.

In short, choosing a library to add to the codebase is an elaborate process requiring a lot of decisions. As the person adding a new dependency, you’ll have answered all these questions beforehand. But the code reviewer on the other side will have no idea about the answers to these considerations. In a pull request based on the code, all the information that they receive is that a new dependency is added.

Seeing a new dependency will raise a lot of questions for the code reviewer, but without context, these will only remain as confusing. This’ll require another back-and-forth, which wasted both your reviewer’s time as well as yours. However, this could very easily be avoided by elaborating on the choice of new dependencies in your pull request.

There’s no need to write an entire essay about your findings and considerations, but a summary of the most important aspects and considerations will suffice most of the time. Doing this will explicitly communicate to the reviewer that you have carefully considered all aspects and that they don’t have to consider the addition of dependencies anymore in their review. Instead, they can focus on reviewing the actual code.

Avoid Complex JavaScript Constructions

Under the hood, React development is for a large part JavaScript development. All of the logic in React is implemented through JavaScript, which in the case of frontend applications are oftentimes the most complex parts. JavaScript as a programming language is very extensive, although not always the most sophisticated one.

For one problem, several JavaScript constructions could be used to address it. In general, JavaScript is not the most straightforward programming language to understand. That’s part of the reason that a lot of tools exist to ensure quality and consistency, which help us with understanding the code. Think of linters, formatters, frameworks, state libraries, and type systems.

On their own, certain JavaScript constructions are more difficult to understand than others. This can be very difficult for code reviewers, as they’ll have to go through the code and understand it. Most of the time, this happens in the browser on platforms like Github where IDE support is almost non-existent yet.

Based on personal experience, common examples of JavaScript constructions that are more difficult to understand are the Array.reduce function, which requires the reader to keep track of a lot of different details in their mental modal, and the AND operator for conditional rendering, which relies on implicit JavaScript behaviour.

That’s not to say that these constructions should never be used. Their main problem is that if developers want to fully understand them properly, it requires them to either have all proper prior knowledge or put more effort into it. In certain teams or scenarios, these could be acceptable. But in general situations, it’s better to avoid these relatively complex JavaScript constructions and opt for ones that are easier to understand, even if they look less pretty.

Provide Additional Instructions On How To Review

On a foundational level, developing in React means we’re working with HTML, CSS, and JS. Depending on whether you use certain frameworks or libraries, the ratio between these three will be different. But in general, the fact that we’re mixing three different technologies means that the resulting code can be verbose and distributed. The composite and reusable nature of React enhances this even further. There are a lot of benefits to this style of programming, but there are also drawbacks.

In particular, the fact that reviewing a React pull request without any assistive tooling like an IDE can be very difficult. There’s a lot of code, which is also distributed over multiple locations and files, and all the different languages are mixed. Without any way of associating them together or determining priorities, it’s extremely confusing and difficult to review these kinds of pull requests.

One way to make your React pull requests easier to review is by giving directions on how to navigate and review your code. Maybe it’s better to start in a particular file. Maybe a specific line of code that is relatively hidden is an important part to understand everything. Maybe it’s better to follow a certain path when reviewing. In a large forest of changed code, every additional instruction you provide can make a world of difference for the reviewer trying to navigate through it.

Final Thoughts

Receiving good reviews on your React pull requests is not only beneficial for the code proposer, but also for the code, the team, and ultimately yourself. The first step towards that goal is making your pull requests easier to review and setting up your reviewers to deliver higher-quality reviews.

To help you with that, this article covered 6 concrete tips on how to make your React pull requests easier to review. These tips involve including the purpose of your pull request, sharing screenshots in case the pull request introduces visual changes, providing the requirements for the feature that is introduced, elaborating on newly added dependencies, avoiding JavaScript constructions that are difficult to understand, and providing additional instructions on how to review.