We need to communicate better when we give people code to review. When we pass off our code to teammates for review, we tend to leave out a lot of the thinking that went into our work. We expect our code changes to speak for themselves. The problem is, unless you’re writing chatbots or speech synthesis software, code can’t speak for itself. That’s our job.
Before we get into this, I want to make sure we’re on the same page. Here at Sparkbox, every line of code is peer-reviewed before making its way into the main codebase. Code reviews are a good thing that your team should do. We use GitHub’s pull requests (PRs) to request code reviews. Our workflow generally looks like this:
Create a branch off of master
Make code changes
Open up a pull request and request a code review from a teammate
Teammate reviews code
If they’re happy with the code, teammate merges your code into the master branch of the codebase
Rinse and repeat. This article focuses on how we can get better at that third step: opening a pull request and requesting a code review. This is the step where you communicate to your teammates the code changes you just made.
The problem is, unless you’re writing chatbots or speech synthesis software, code can’t speak for itself. That’s our job.
Writing about code isn’t an easy task. Most of the time, loads of thought is put into the work behind a pull request. And that thought doesn’t easily translate into written words. It’s hard to take hundreds of lines of changed code—plus the thinking behind them—and distill all the gotchas and tricky bits down into a readable paragraph or two. Since it’s difficult, a lot of people don’t even bother. I can’t blame ‘em.
Because code can be so hard to distill into words, I’ve been trying something different lately: I’ve been making screencasts to explain my pull requests. These screencasts usually demo what I’ve been working on, and then walk through the code I wrote to make it happen.
Recording the video itself is pretty easy. The simplest option I’ve found is a Chrome extension called ViewedIt, which lets you handle screen recording and hosting right from your browser. It’s quick, free, easy, and I promise I’m not getting paid to say that. If you’d prefer, you could also record your screen another way, then share the video through something like Dropbox or Slack. Whatever. You do you.
I think there are two reasons why screencasts make you better at documenting your code. First, it’s easier. Second, it’s more personal.
It’s Easier
Writing down coherent thoughts takes time and energy. Creating a good, thorough PR description that hits all those talking points I mentioned earlier is a chore, and it doesn’t always feel worth it.
Speaking, instead of writing, removes a lot of this friction. It feels more like a quick conversation, and less like writing documentation. It’s easier to express more, while exerting less mental energy. And when things are easier, we’re more likely to do them.
It’s More Personal
When you record a video to send to somebody, you’re forced to remember that there’s a human on the other end of the computer. It stirs up empathy. If you’re speaking directly with a teammate about your code changes, it’d feel weird (or even inconsiderate) not to tell them where to test your code. But we do this all the time when we’re communicating via text. It’s harder to throw code over the wall when you remember there’s a human on the other side who has to catch it.
Sometimes a PR has a clear paper trail behind why it was created. Oftentimes it does not. I’ve found that it’s natural to give more context behind a PR’s history when you’re communicating through video. This context can make a world of difference for the reviewers looking at your code. It will help them know how to look at your code, and also help them better understand the project as a whole.
What to Include in Your Screencast
When I record a screencast for a PR, my talking points usually look something like this:
Why the code was written in the first place. This isn’t always clear. Even if a pull request is associated with a GitHub issue or JIRA card, these aren’t always clearly written or easy to follow. It’s helpful to have an up-to-date description of what was done and why, straight from the author.
Where you can see the results of the code. Nothing is more frustrating than receiving a pull request and not knowing where you can see the results of what was added or fixed. This is mostly important for UI-related changes that have visible effects on the front-end. This can be easily remedied by seeing a quick demo of the work.
Explanations for any weird or dodgy bits of code. Hopefully you’re already documenting any questionable code through comments. Still, it never hurts to provide a video walkthrough that explains the ins and outs of hard-to-follow code.
Any other points of interest in the code changes. Pull requests are rarely as straightforward as we like them to be. Authors usually have a clear intention when they set out to complete a task, but sometimes that first task sets off a chain reaction. This can’t always be avoided, and you should fill in your reviewers so they know what to expect.
Notice how none of these bullet points are specific to screencasts or communicating with video? They’re just guidelines for giving teammates good, thorough pull requests. There’s no reason you can’t do this with plain old text, but if you’re recording a video to explain your code changes, this stuff comes out naturally. And I think there’s something to that.
Screencast Guidelines
Communicating with video is a little weird. Here are some tips to help you get started:
Not every PR needs a video. Not all PRs are created equal. Some PRs already have plenty of context, or are so small that creating a video walkthrough would be overkill. Sometimes a short written explanation is plenty. Only add a screencast for PRs that could use a little explaining.
Keep it brief, but informative. A video should only be as long as it needs to be, though I still prefer to err on the side of giving too much information. A beefy PR deserves a beefy explanation. My longest video has been 21 minutes (sorry, Nate). But it was a complicated chunk of code, so it warranted the length.
Still write some. You should still provide some kind of written record with your PRs. It’ll be useful as a quick reference, and it’ll last longer than your videos. Videos shouldn’t be critical to understand a PR. This is especially important because there’s a good chance your video links will break in the future. Videos should be treated as a supplementary form of communication, not the primary one.
Show your face. Lots of screen recording options let you overlay a feed from your webcam on the video. This one is totally optional, but I think a disembodied voice can feel a little impersonal. Showing your face is a nice way to remind the reviewer that there’s a human on the other end.
Consider security. Whenever you bring a new service into the mix, you’re potentially opening up a security loophole. This should be taken into account when you’re deciding where to put your videos.
Have fun. If you have fun with it, these screencasts will be more enjoyable for you and the person reviewing your stuff. Plus, that’s always the last step in these kinds of lists.
Give It A Shot!
I hope you give this a try. I haven’t been doing this for a long time, but people seem to be liking it. If you do decide to try it out, we’d love to hear about it on Twitter!
