About pull request review

Everybody benefits from code review: The reviewer, the reviewee and whoever comes to look at the reviewed code later!

To quote Parker 2017:

Code review will not guarantee an accurate analysis, but it’s one of the most reliable ways of establishing one that is more accurate than before.

The mechanics of code review:

1. A problem is identified
2. An issue is filed that describes that problem
3. A writer files a pull request that contains changes that addresses the problem.
4. A reviewer reviews the changes on that pull request.
5. The reviewer reviews and recommends edits to those changes or accepts them as is.
6. The writer incorporates those changes as best they can.
7. (Steps 4-6) with comments between the are repeated until the reviewer and writer accept the changes.
8. Changes are added to the code base by merging the pull request.
9. A new problem is identified (and the whole cycle starts again).

That's the workflow, but how do you get the most out of code review, both as the reviewer and writer? Here's some tips about getting the most out of code review:

Tips for the writer

• Put context around the changes you are proposing, linking any relevant issues, prior pull requests, or relevant code/media.
• Review your own pull request before requesting the review of someone else; check the Files Changed tab.
• If a pull request is still in progress change it to a draft so no one reviews it before you are ready.
• Try to make sure your pull requests aren't too long! Code reviewing fatigue is very real.
• Highlight for the reviewer what kind of feedback you are looking for.
• Try to explain or ask for help on any peculiar parts of your PR or if there's any parts you are stuck on.
• Accept reviews with a helpful frame of mind -- it's perfectly okay to be wrong!

Tips for the reviewer

• Check that the pull request meets the goals that the writer is intending.
• If you don't understand, ask more questions!
• Take careful review of areas that are more complex or seem odd.
• Give reviews loaded with empathy and positivity !
• Utilize suggestions where possible.
• If you are completely lost, don't be afraid to ask the writer to reconfigure or expound on what they mean.

Recommended reading:

• Effective code reviews
• 9 Tips for Opening a Better Pull Request
• Writing proper GitHub issues
• On Empathy and Pull Requests
• Best practices for Code Review
• Writing Great Scientific Code
• Six Commandments for Writing Good Code