Navigation Menu

Skip to content

Instantly share code, notes, and snippets.

@justinabrahms

justinabrahms/code_review.md

Forked from marionzualo/code_review.md
Last active August 29, 2015 14:22
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save justinabrahms/4525b90c54fe3aa623c6 to your computer and use it in GitHub Desktop.
Save justinabrahms/4525b90c54fe3aa623c6 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
code_review.md

Code Review

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

Purpose

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.

Everyone

  • 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 :user_id?")
  • 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 [4] and pull request descriptions.
  • Use the pull request description template [3]. You only need to answer the relevant questions. Pro tip: use the bookmarklet [11] or chrome extension [12] 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.

Reviewing Code

  • 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 [9] [7].

Links

Links from places on the Internet that helped write this:

(The most useful ones are [9], [1], [3] and [2].)

Raw
pull_request_template.md

What's this PR do?

Where should the reviewer start?

How should this be manually tested?

Any background context you want to provide?

What are the relevant tickets?

Screenshots (if appropriate)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment