Skip to content

Instantly share code, notes, and snippets.

@t3hcr

t3hcr/code_review.md

Forked from marionzualo/code_review.md
Created June 10, 2016 03:31
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save t3hcr/e1fb3e513af71931812a971eb26202d3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save t3hcr/e1fb3e513af71931812a971eb26202d3 to your computer and use it in GitHub Desktop.
Download ZIP
Code Reviews
Raw
code_review.md

Code Review

A guide for reviewing code and having your code reviewed.

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
  • provide opportunities to educate junior engineers
  • catch poor architectural decisions and bugs

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

  • Be grateful for the reviewer's suggestions. ("Good call. I'll make that change.")
  • Don't take it personally. The review is of 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.
  • 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]. Or better, bookmarklet [11] or crhome extension [12].
  • Annotate your code reviews. Add comments anywhere that you feel will help the reviewer understand your code.
  • Review your code before anybody else

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).

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.
  • Compliment/reinforce good practices

Some suggestions of things to look for when reviewing code:

  • Is all the code easily understood? 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 etc.
  • Do tests exist and are they comprehensive?)
  • Does the code work? Does it perform its intended function, the logic is correct etc.

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:

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