This document provides guidance on how to conduct a useful code review for a pull request. It recommends discussing code changes beforehand, providing context for the pull request, reviewing code for bugs and completeness, considering cross-cutting concerns like performance and security, and leaving constructive comments that are kind, honest, restrained, and helpful. The overall goal is to have a productive conversation around the code changes to improve quality.
5. How to get a useful review
● Story kickoffs
● Talk to each other about what you’re working on
● Encourage pairing where feasible
● Codify your team’s standards where possible e.g. ESLint, .editorconfig
● Find opportunities to discuss your team’s design outlook / rules of thumb
/ accepted approaches
● Review your own PRs
● Read other people’s PR reviews
● Open a PR that’s easy to review
6. Meaningful name
Meaningful branch name
Say why we’re making the change
Link to a ticket, other relevant resources or
PRs
List what PR does / changes
Screenshots of UI changes
7. Call out tradeoffs you’re aware of, ask questions and call
out points for discussion
Small, specific PRs
Describe approach
9. What does LGTM mean?
Can’t see anything wrong with this?
Not sure what this is about, but it doesn’t get in my way?
This is the right thing?
10. Form an opinion
😀😰😕🙀🥳🤯
● Be clear on your expectations
● Do I like this feature?
● What approaches would I have considered? Which would I prefer?
● Am I worried about anything?
● What is the impact of this change on our team (e.g. support), product (e.g.
usage), business (e.g. money) and user (e.g. ease of use)?
12. Read through the PR to understand:
● Intent of the person
● The approach being used
● Overall shape of the changes. More server or more UI? Are there new
libraries in package.json? Config changes? New database queries?
● Add comments as you go - use the GitHub review feature so comments
aren’t final. You can even use comments to ask yourself questions or
remind yourself to think about something.
13. Go through the PR again and add comments
Take
your
time.
Reviewing PRs is important.
15. How much code has changed?
Match the changes to the PR description :)
16. The basics
Is the code:
1. Correct (look out for bugs)
2. Complete (think of cases it doesn’t handle)
3. Easy to understand (the harder a PR is to review, the more your review can help!)
4. Focused (does the code do too much?)
5. Well-tested
6. Well-enough documented (usually not a lot required, but may need something in the readme or team wiki)
17. Question things
If something strikes you as odd or stands out, give it some more thought:
● Why is it done in X way?
● How else could it be done?
● Does it need to be done at all?
18. Play with the code
Open an editor or the node interpreter
19. No file is an island
Think of the overall shape of the changes, not just the lines in front of you:
● Could a different design/approach make the code simpler to work with in
future?
● Remember that the answer to making the function you’re looking at
simpler is often in another file altogether!
20. Where are you?
Think of the design paradigm you’re in and its associated best practices, e.g.
● What is the conventional way to do X in React?
● What is the best way to do Y when using Postgres?
21. If things get sticky...
● Pull the code
● Run it locally
● Get on a call
22. Cross-cutting concerns
● Performance (e.g. is the new Mongo query covered by an existing index?
Are we making unnecessary calls to the database? Are we iterating over a
collection too many times?)
● Security (do we have the right permission checks?)
● Error handling, metrics & logging, auditing
● Devices and browsers: Internet explorer quirks, mobile UX
● Integration points: e.g. mobile app, data warehousing. Are you breaking
any contracts?
23. Think about the big picture
Is this the right approach/design?
Is this the right code base?
Is this the right feature?
Is this the right time?
Is this right for the product?
Does this support the business objectives?
24. Before you submit
● Take a step back and ask yourself again: does the PR make sense? Does
the feature make sense? Do the product goals make sense? (You know
more about this change set now than you ever will again.)
● Look at your PR review from the perspective of the person getting it. Have
you explained yourself clearly? Have you been kind and helpful?
● If you’re at all excited about hitting the green button, go make a cup of tea
27. Be honest.
● Leaving something important
unsaid will not help the
person in the long term.
● If you’re worried about how it
will make someone feel,
rather work on the way in
which you deliver the
feedback (e.g. maybe a public
GitHub review isn’t the right
thing).
28. Be restrained.
Think carefully about your
comments before making them. Is
this PR the right place to rant
about redux? Would using
currying or ES6 classes really
improve the code (even though
you think they’re awesome right
now)?
29. Be helpful.
● Offer people concrete steps
they can take to improve their
code - PR reviews should be
learning opportunities.
● Don’t just mention Mongo’s
index selectivity - add a link to
the relevant documentation
or a StackOverflow question.
