A guide for reviewing code and having your code reviewed.
Peer code reviews are the single biggest thing you can do to improve your code - Jeff Atwood
Code review is an important part of a team's development process. It helps to:
- disseminate knowledge about the codebase/technology/techniques across teams
- increase awareness of the features being developed
- provide opportunities to educate junior engineers (actually all engineers)
- find alternative solutions to problems
- catch poor architectural decisions and bugs
- develop a sense of team ownership of the code (no more his/her code)
When doing code reviews, the process is as important as the result, therefore, some guidelines are presented below to help improve the process of code review.
- Accept that many programming decisions are opinions. Discuss tradeoffs, which you prefer, and reach a resolution quickly.
- Ask questions; don't make demands. ("What do you think about naming this
- Ask for clarification. ("I didn't understand. Can you clarify?")
- Avoid selective ownership of code. ("mine", "not mine", "yours")
- Avoid using terms that could be seen as referring to personal traits. ("dumb", "stupid"). Assume everyone is attractive, intelligent, and well-meaning.
- Be explicit. Remember people don't always understand your intentions online.
- Be humble. ("I'm not sure - let's look it up.")
- Don't use hyperbole. ("always", "never", "endlessly", "nothing")
- Don't use sarcasm.
- Talk in person if there are too many "I didn't understand" or "Alternative solution:" comments. Post a follow-up comment summarizing offline discussion.
Having Your Code Reviewed
- Review your code before anybody else.
- Provide context about what the change is and why is it important - Write informative commit messages  and pull request descriptions.
- Use the pull request description template . You only need to answer the relevant questions. Pro tip: use the bookmarklet  or chrome extension  for pull request description templates.
- Annotate your code reviews. Add comments anywhere that you feel will help the reviewer understand your code.
- Be grateful for the reviewer's suggestions. ("Good call. I'll make that change.")
- Don't take it personally. The review is about the code, not you.
- Explain why the code exists. ("It's like that because of these reasons. Would it be more clear if I rename this class/file/method/variable?")
- Seek to understand the reviewer's perspective.
- Try to respond to every comment.
- Wait to merge the branch until Continuous Integration tells you the test suite is green in the branch.
- Merge once you feel confident in the code and its impact on the project.
- Code review often and for short sessions. The effectiveness of code review drops after around an hour. Set aside time throughout your day to coincide with breaks in order to not disrupt your flow.
- Review at least part of the code, even if you can't do all of it.
- Review the right things, let tools to do the rest. Don't focus on reviewing things that can be reviewed by tools (e.g. Rubocop, jsLint, sass lint, etc). If the tools don't provide good feedback, change the config or improve the tools.
Understand why the code is necessary (bug, user experience, refactoring). Then:
- Communicate which ideas you feel strongly about and those you don't.
- Identify ways to simplify the code while still solving the problem.
- If discussions turn too philosophical or academic, move the discussion offline. In the meantime, let the author make the final decision on alternative implementations.
- Offer alternative implementations, but assume the author already considered them. ("What do you think about using a custom validator here?")
- Seek to understand the author's perspective.
- Sign off on the pull request with a
👍or "Ready to merge" comment... always!
- Compliment/reinforce good practices.
Some suggestions of things to look for when reviewing code:
- Is all the code easily understood? Is code unnecessarily complex ?
- Can variable/method names be improved?
- Are classes/files/methods becoming too large? Should they be split into smaller pieces?
- Does it conform to the agreed coding conventions?
- Is there any redundant or duplicate code? Is the code as modular as possible?
- Could the design of the solution be improved (e.g. single responsibility principle, open/closed principle) ?
- Is the code testable? (i.e. don't add too many or hide dependencies, unable to initialize objects, test frameworks can use methods, do tests exist and are they comprehensive?)
- Does the code work? Does it perform its intended function, the logic is correct etc.
- Things related to your area of expertiese
Pro tip: Keep your own checklist of things you look for in a code review as in  .
Links from places on the Internet that helped write this:
(The most useful ones are , ,  and .)
-  Talk - Implementing a Strong Code-Review culture - the talk that inspired this.
-  Thoughtbot's Guide for Code-Review - straight to the point guidelines on code review. A lot of the content was taken from there.
-  Pull request templates make code review easier - introduction to pull request templates.
-  some articles on how to write good commit messages - first, second, third
-  Am I My Code? - this article explores some strategies for giving feedback when reviewing code.
-  Code review at the Dropbox iOS team - the article goes over their whole process of review. It has some interesting ideas.
-  Code Review Checklist - from Fog Creek Software
-  Effective code review tips - from Fog Creek Software
-  Code Review Best Practices - really good article on code review best practices
-  11 proven practices to improve code reviews - nice article backed by data from studies.
-  Pull request template bookmarklet
-  Pull request template chrome extension