I’m a software engineer lead at unosquare who has spent the past decade plus of my career crafting software in domains ranging from the medical industry to the church market. I live in Fort Wayne, Indiana with my wife and son. We love traveling, woodworking, and reading!
As a primary backend developer, one of the most ambiguous parts of my job involves frontend code reviews. Give me a Ruby on Rails PR and I can nitpick it all day long but send me a React PR and I feel like I’m being asked to review an academic paper on the latest developments in String Theory. Part of the issue is that frontend code necessarily contains a significant amount of boilerplate code (CSS and HTML come to mind.) It can be difficult to tell what’s good and what could use improvement when your eyes are lost in a sea of green text:
So, I asked some of our frontend developers at Unosquare if they had any tips for creating or reviewing frontend PRs. I’d love to share some of their suggestions!
Tip #1: Add Screenshots!
Kudos to Vincent Lopez, one of our backend developers, for contributing this tip! Far and away the most useful tip our team has found with front-end code reviews is that they need screenshots, videos, or a demo app showcasing the UX/UI look and feel. Is there enough contrast? Do the designs look consistent with other areas of the app? Are the animations smooth? Is the flow between screens logical? These aspects of front-end features are nearly impossible to decipher by simply staring at code, but add a visual layer atop the review, and all of a sudden you gain a more complete picture.
Here’s a couple of real-world examples of how Rich Dubay (one of our Unosquare front-end developers on the Solid Lives team) structures his frontend PRs:
The compression is difficult to see in the screenshot, but you get the idea from the combination of the title, description, and screenshots exactly what the problem was and how it looks after it’s been fixed.
Here’s another one of Rich’s examples:
The before and after images clearly show how the wrapping bug was fixed. This is not only helpful for other developers, but it also gives the QA tester confidence in what they should expect the screen to look like after the fix is deployed to the testing environment.
Tip #2: Add Descriptive Comments
You may have heard developers say “Let the code speak for itself. Avoid comments!” I agree that you should attempt to make your code as self-descriptive as possible; however, there is a critically missing piece of information in that advice: source control comments are extremely valuable. They provide critical information relevant to the entire context of the change and are a developer’s opportunity to explain themselves to other developers in the most natural way possible. I’ll let Josh Babcock, another one of our front-end Unosquare developers on the Solid Lives team, demonstrate this with one of his recent PRs:
In my opinion, this is a remarkably descriptive PR. It’s got it all:
- The ticket number related to the change: “Jb/sljd 1105 edit”
- A description of the scope of this change: “This is for Graduation tickets 1-5 (if curious all are in code review”)
- A list of API changes
- A list of major changes, particularly noting new UI elements
- Todo items: “***** I left out some Spanish strings. I’m waiting for Stepf to finish the media library tickets first.”
- Screenshots (as we expressed in Tip #1)
The changes above are considerations you should be thinking about when creating a PR for a front-end code review (frankly, even for a back-end review.)
Tip #3: Be Proactive with Questions
One of the most useful features of Github is the ability of the PR author to post comments on specific lines of code. This is remarkably useful for asking questions such as, “Is this the best way to do this?” or “I had to do it this way because…” This clues other developers in that they should pay special attention to the lines of code mentioned and offer follow-up if needed. Here’s Josh and Rich with a good example of that:
Josh is humble enough to ask about whether his solution is the best way to do something, and Rich responds with not only a clear and concise opinion, but also an example of how he could refactor it. These types of discussions are wonderful async ways to pair program. We do our best work as developers when we have team members supporting us!
Tip #4: Consider The Various Visual States (Matt Koehler)
While the above tips were a bit more meta, this one from one of our front-end developers, Matt Koehler, is more concrete. He suggests thinking about what a screen should look like when it’s in various states. For example, what should a screen look like when it’s loading? If you’re reviewing the PR, you can easily look for elements like spinners or loading text in the code to double check their presence as well as examining screenshots of the app in action.
Form state is another aspect to consider. If data is invalid, avoid confusing your user with disabled submit buttons. Instead, keep the buttons active but display a helpful error message on press explaining why the form can’t be submitted. Like loading states, this can be inspected in a PR by examining the form code’s onSubmit logic. Are there good validation messages in place? What does the form submission look like in an invalid state? When authoring a PR, adding screenshots showcasing the invalid form state alongside the valid state are very useful for this reason.
Conclusion
I’m sure there are dozens of other tips for front-end code reviews. These are but a few, but I hope you will find them helpful in your future reviews. Most of all, I hope they will get you thinking about the various ways you can both author and review front-end code.
We developers are often so excited that we’ve completed coding a feature that we forget that simply pushing code is by no means the last step in its journey. Avoid hitting the “Create Pull Request” button and blindly leaving the defaults in place. Think about what it is you want to communicate with your team that will help make the code the best it can possibly be.
Similarly, when reviewing large chunks of code, avoid cursory scans and instead visualize what it’s like when it’s actually running in the user interface. Examine it like a sculpture from different angles. Inspect it in various lights. There’s much more to front-end code than meets the eye, but if we consider it critically, we can improve the UI and UX, avoid bugs, craft clean code, and better communicate with fellow team members. Happy reviewing!
