Skip to content

Faster UI Code Reviews Using Screenshot and Video Diffs


Code review is an integral part of multiple developers working on the same project, whether you are on a team of developers, or contributing changes to public open source projects. In either case, the reviewer needs to be comfortable with your changes before they will merge them.

This leads to one law of code review: The clearer it is to the reviewer what changes you made, the faster the reviewer can review and merge your changes.

Unfortunately, this gets complicated when you’re developing iOS UI. Whether your team has chosen Storyboards, programmatic UIs, or a combination of the two, reading either Storyboard XML or code diffs is really hard to visualize for anything beyond trivial changes. Worse, if you have a combination of storyboards and code — which is often the case — you can’t necessarily trust that the storyboards before and after even look like what the app does.

To make the intent of your changes clear, you need another way to show that diff. For larger UI changes, representing those diffs as either screenshots or video is key in making those changes as clear as possible.


If it is easy enough to get your point across with a before and after screenshot of the UI, then it’s easy to do either through the Simulator or on device.

Simulator: Press Command-S to take a screenshot.

On device: Press the sleep button, followed quickly by the home button (or volume up on devices with no home button).

If you have a multi-step process, or need to show something dynamic, video is the way to go. Quicktime Player can record a video of your interaction with an app either through the Simulator or on device.

Simulator:

  • Open Quicktime Player, and select File -> New Screen Recording
  • Drag a box around the simulator screen and then click Start Recording.
  • When done, click the Stop icon in the menu bar, Stop button on the Touch Bar, or press Command-Control-Esc.

On device:

  • Connect your device to a Mac via lightning cable.
  • Open Quicktime Player, and select File -> New Movie Recording
  • Click the arrow to the right of the record button, and select your device as the Camera and Microphone.
  • Click the record button.
  • When done, click the Stop button.

You have a .mov file now, but none of the popular git services or bug trackers accept video attachments. They will however accept animated .gifs, so the last step before upload is to convert your screen capture. Luckily there is a quick open source tool to do that.

Update – May 13, 2021: GitHub now supports uploading .mov and .mp4 files directly into a Pull Request. Check out the details on their blog, or if you are still using an alternative that does not support full video files yet, read on.

Download Drop to GIF, install, and open. It is a simple drag-and-drop interface, although you may want to click the gear to configure settings to make the file smaller. I generally choose to uncheck Match original and set the FPS to 10. The quality slider doesn’t have a huge impact on size, and keeping fidelity in these images is reasonably important, so I generally leave quality at maximum.

Once you have your .gif, you can easily drag and drop into your Pull Request, if you’re using GitHub, Gitlab, etc., or upload into your bug tracking tool of choice. It’s a little bit of extra work upfront, but pays off by making your code reviews faster for the reviewer — and faster and more successful for you.

Comments are closed.