Skip to content

Instantly share code, notes, and snippets.

@porterjamesj
Last active October 20, 2022 22:46
Show Gist options
  • Save porterjamesj/002fb27dd70df003646df46f15e898de to your computer and use it in GitHub Desktop.
Save porterjamesj/002fb27dd70df003646df46f15e898de to your computer and use it in GitHub Desktop.

Code Review

A consolidation of advice and stuff from the internet

What is code review?

Code review one person reading over another's code and offering comments, suggestions, and feedback about how it could be improved. Often this is done at companies or in open source projects as a required step before proposed changes can be merged into a codebase. Typically this happens asynchronously (i.e. someone submits code to be reviewed, at some later time the reviewer makes comments and suggestions, and then the submitter resonds to them even later).

Here are a few examples of code review in the wild:

Why?

  1. Find Bugs. A second pair of eyes is often very helpful for finding bugs, defects and edge cases you wouldn't have noticed yourself.
  2. Improve Readability. Having someone else read your code and say which parts are confusing and why will tell you what changes you could make to make your code easier to read and understand.
  3. Improve Design. Someone else looking at your code might have an idea for a different, much better way of solving the problems your code does!
  4. Learning and Growth. No two people have the same set of programming skills and knowledge. Having one person read another's code and comment on it is a great way for both people to learn things they didn't know before.

Tips for giving review

  • Review relatively short pieces of code at a time, < 500 lines, ideally close to 200 or 300.
  • Determine what kind of feedback the reviewee is looking for and try to keep your review focused on this.
  • Avoid ad hominems (e.g. "what if we did this?" rather than "you shouldn't do that"). The point is to give constructive suggestions about how to improve code, not attack individuals. The goal is for everyone to improve, not for anyone to feel bad about themselves or their work.
  • Avoid nit-picking style and formatting, these things can be checked/fixed using tools like go fmt and pep8/pycodestyle if the reviewee is interested in them.
    • this isn't to say that you shouldn't e.g. suggest clearer names for variables, just don't be pedantic about it (consider why you are saying this)
  • Focus on design choices, interrogate why code works the way it does, how it could be changed or refactored to be more clearly structured, readable, or performant.

Tips for getting review

  • Think about and clearly express to the reviewer what you're looking for feedback on. For example maybe you're particularly interested in how to make the code faster, or there's a particularly complicated part of the code you think might be buggy, or the code is written in a language you're learning and you just want to learn how to write more idiomatic code in that language.
  • Keep an open mind and try not to be defensive. Getting critical feedback on things you're proud of and worked hard on can be difficult, but we all have things we could improve on. Assume good faith on the reviewer's part and remember that their goal is to help you improve your code, not attack you personally.
  • The above point isn't to say that you shouldn't respond to the reviewers comments. Explaining why you made the decisions you did, expressing uncertainty about things, etc., are all fair game.

References

(aka the stuff I cribbed to make this document, there are basically no original thoughts here, it's all taken from the below, or other things linked therein)

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