KA Engineering

KA Engineering

We're the engineers behind Khan Academy. We're building a free, world-class education for anyone, anywhere.

Subscribe

Latest posts

Working Remotely

Scott Grant on October 2

Tips for giving your first code reviews

Hannah Blumberg on September 18

Let's Reduce! A Gentle Introduction to Javascript's Reduce Method

Josh Comeau on July 10

Creating Query Components with Apollo

Brian Genisio on June 12

Migrating to a Mobile Monorepo for React Native

Jared Forsyth on May 29

Memcached-Backed Content Infrastructure

Ben Kraft on May 15

Profiling App Engine Memcached

Ben Kraft on May 1

App Engine Flex Language Shootout

Amos Latteier on April 17

What's New in OSS at Khan Academy

Brian Genisio on April 3

Automating App Store Screenshots

Bryan Clark on March 27

It's Okay to Break Things: Reflections on Khan Academy's Healthy Hackathon

Kimerie Green on March 6

Interning at Khan Academy: from student to intern

Shadaj Laddad on Dec 12, 2016

Prototyping with Framer

Nick Breen on Oct 3, 2016

Evolving our content infrastructure

William Chargin on Sep 19, 2016

Building a Really, Really Small Android App

Charlie Marsh on Aug 22, 2016

A Case for Time Tracking: Data Driven Time-Management

Oliver Northwood on Aug 8, 2016

Time Management at Khan Academy

Several Authors on Jul 25, 2016

Hackathons Can Be Healthy

Tom Yedwab on Jul 11, 2016

Ensuring transaction-safety in Google App Engine

Craig Silverstein on Jun 27, 2016

The User Write Lock: an Alternative to Transactions for Google App Engine

Craig Silverstein on Jun 20, 2016

Khan Academy's Engineering Principles

Ben Kamens on Jun 6, 2016

Minimizing the length of regular expressions, in practice

Craig Silverstein on May 23, 2016

Introducing SwiftTweaks

Bryan Clark on May 9, 2016

The Autonomous Dumbledore

Evy Kassirer on Apr 25, 2016

Engineering career development at Khan Academy

Ben Eater on Apr 11, 2016

Inline CSS at Khan Academy: Aphrodite

Jamie Wong on Mar 29, 2016

Starting Android at Khan Academy

Ben Komalo on Feb 29, 2016

Automating Highly Similar Translations

Kevin Barabash on Feb 15, 2016

The weekly snippet-server: open-sourced

Craig Silverstein on Feb 1, 2016

Stories from our latest intern class

2015 Interns on Dec 21, 2015

Kanbanning the LearnStorm Dev Process

Kevin Dangoor on Dec 7, 2015

Forgo JS packaging? Not so fast

Craig Silverstein on Nov 23, 2015

Switching to Slack

Benjamin Pollack on Nov 9, 2015

Receiving feedback as an intern at Khan Academy

David Wang on Oct 26, 2015

Schrödinger's deploys no more: how we update translations

Chelsea Voss on Oct 12, 2015

i18nize-templates: Internationalization After the Fact

Craig Silverstein on Sep 28, 2015

Making thumbnails fast

William Chargin on Sep 14, 2015

Copy-pasting more than just text

Sam Lau on Aug 31, 2015

No cheating allowed!!

Phillip Lemons on Aug 17, 2015

Fun with slope fields, css and react

Marcos Ojeda on Aug 5, 2015

Khan Academy: a new employee's primer

Riley Shaw on Jul 20, 2015

How wooden puzzles can destroy dev teams

John Sullivan on Jul 6, 2015

Babel in Khan Academy's i18n Toolchain

Kevin Barabash on Jun 22, 2015

tota11y - an accessibility visualization toolkit

Jordan Scales on Jun 8, 2015

Meta

Tips for giving your first code reviews

by Hannah Blumberg on September 18

At Khan Academy, (nearly) every piece of code that goes into our codebase has been reviewed by at least one other person. Code reviews help us keep code maintainable and clean, catch big-picture issues early, build a shared understanding of the codebase, and socialize new engineers. To learn more about our code review beliefs and practices, check out some oft-cited blog posts here and here.

When I joined Khan Academy as an intern, I read a ton of documents describing the purpose, importance, and process of code reviews. Since I was a college student at the time and was accustomed to receiving feedback from professors, I felt prepared to have my code reviewed. I did not feel prepared, however, to begin reviewing code myself.

Reviewing other people's code – especially code written by smart, experienced engineers – can be really intimidating. What could I, an intern with just a few computer science courses under my belt, contribute?

Now that I have completed my internship and have been full time at Khan Academy for over a year, I know that everyone – even the newest of interns – can add value to the code review process.

To help you get started, here are some concrete suggestions for reviewing code for the first time:


1. Ask questions

This is probably my favorite piece of advice for getting started with code reviews. Code review comments do not have to be direct requests for changes. You might ask the author to describe the trade-offs they considered, explain how a piece of code works, or provide more context on the project.

Asking questions gives you the opportunity to learn and gives the author the opportunity to articulate, clarify, or challenge their thinking. It may also help the author identify areas of the code that are less clear and consequently harder to maintain.

Example of asking questions

If you find a mistake or identify an area of improvement while doing a code review, you should absolutely feel empowered to share that directly. It's easy, though, to second guess yourself, especially when reviewing an experienced engineer's code. If you find yourself about to delete a code review comment, try rephrasing it as a question! Asking a question is often just as valuable to the author, and it may feel a little easier to post.

Example of asking questions

2. Try pair reviewing

This is a tip I learned from one of our engineering managers, Celia La. Ask your mentor or onboarding buddy (or anyone else on your team) if they would be willing to do a "pair review" session. You and your teammate can sit together or screen share as you work through a code review together.

By watching and asking questions, you can learn more about your teammate's process and techniques.

If you are not able to set up a pair review session, you can also look at code reviews that your teammates have done for one another. Although you may not learn your teammates' processes, you will still get a sense of the type of feedback they give one another.

3. Review code in your IDE

This tip comes from former engineering lead and my onboarding buddy, Charlie Marsh. In Charlie's blog post, he describes the benefits of reviewing code in your own integrated development environment (IDE).

At Khan Academy, we typically review code through Phabricator's web interface. The arc patch command allows you to apply the changes in a code review to your local copy of the codebase. From there, you can explore the code in your own IDE.

As Charlie describes, reviewing code in your IDE allows you to put yourself "in the author's shoes" and catch things you might not see in the web interface. You can navigate more naturally between files and see changes in the context of the codebase.

Reviewing code in an IDE also allows you to try out ideas before you share them so that you can suggest changes with more confidence.

4. Comment on anything

When you are doing your first few code reviews, you should feel free to comment on anything.

For example, you should feel comfortable pointing out small fixes that are not blocking. Although you will likely move away from these comments over time, they can help you build confidence.

If you leave "nit" (short for nitpick) level comments, it is best to distinguish them from more crucial fixes. I generally like to add the word "nit" before these comments to communicate to the author that they are not blocking.

Example nit comment

Borrowing from Ben Kamens' blog post, you should also feel free to "point out the good stuff" in your comments. You might thank the author for a really helpful comment, call out a clever (but clear!) technique, or compliment the thoroughness of their testing. These comments encourage the author to continue doing the "good stuff" and help to build relationships.

Example compliment

Example compliment

5. Review a peer's code

Even if you are a very new or junior engineer, you can add value to any code review. That being said, it can be extra intimidating to review code written by experienced engineers. To become more comfortable and build your confidence, try finding someone who you consider a peer (maybe a fellow intern or someone who started around the same time as you) and ask if they would be interested in having their code reviewed by you and vice versa.

Reviewing a peer's code can be a more comfortable introduction to code reviews. It will also give you extra opportunities to practice! Keep in mind that you do not need to be the sole reviewer of your peer's code; you can leave comments without approving or rejecting the change.


Reviewing code is a skill that develops over time. The first step to improving is to just get started!