Behaviour and protocol
- For discussions that are happening outside a PR, summarize them afterwards as a comment for future reference.
- Code reviews are discussions where everybody is encouraged to chime in irrespective of their job title.
- Words such as “just”, “simply”, and “easily” tend to pass judgment about the difficulty of a problem.
- Always read your comment from the perspective of the author of the pull request.
- If you see something good, say something good.
- Suggest specific changes rather than using phrases such as “What do you think about clarifying X?” and explain why a change might be appropriate.
- Avoid selective ownership of code (“yours”, “mine” etc.).
- Consider reading the code changes from the bottom to the top to catch issues that others might overlook (as most people tend to read the code from the top to bottom).
- The feedback is not a critique of you but the code.
- Be grateful for the reviewer’s suggestions.
- Provide context to the pull request and explain the motivation for it.
- Add comments to specific lines where you want feedback or have questions.
- Add comments to specific lines where you anticipate questions and explain why you changed something.
- Every comment should be seen as a suggestion. Ask questions until you understand it and agree that the change would be an improvement.
- Tag the appropriate people in the PR (
git annotatecan be useful here).
- Add a link to the ticket in Asana, Trello, JIRA etc.
- For frontend changes, consider including GIFs or screenshots showing what has changed.