Code Review Guide

Follow these guidelines when reviewing code or having your code reviewed. Full reference: https://github.com/ookamiinc/guides/blob/master/code_review.md

General Etiquette (Everyone)

Accept that many programming decisions are opinions. Discuss tradeoffs, state your preference, and reach a resolution quickly.
Ask questions instead of making demands. ("What do you think about naming this :user_id?")
Ask for clarification when something is unclear. ("I didn't understand. Can you clarify?")
Avoid selective ownership of code ("mine", "not mine", "yours").
Avoid terms that refer to personal traits ("dumb", "stupid"). Assume everyone is attractive, intelligent, and well-meaning.
Be explicit. People don't always understand 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.
If too many "I didn't understand" or "Alternative solution:" comments arise, move to a synchronous conversation. Post a follow-up comment summarizing the offline discussion.

Be grateful for suggestions. ("Good call. I'll make that change.")
Don't take feedback 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?")
Extract unrelated changes and refactorings into future tickets/stories.
Link to the code review from the ticket/story.
Push feedback-based changes as isolated commits (do not squash until ready to merge) so reviewers can read individual updates.
Try to respond to every comment.
Wait for CI to pass before merging.
Merge once you feel confident in the code and its impact on the project.

Understand why the code is necessary (bug fix, UX improvement, refactoring) before reviewing.
Communicate which ideas you feel strongly about and which you don't.
Identify ways to simplify the code while still solving the problem.
If discussion becomes too philosophical, move it offline. 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 thumbs-up or "Ready to merge" comment.

When a style guideline is missed, comment with a reference to the guideline.
If you disagree with a guideline, open an issue rather than debating it in the code review. Apply the guideline in the meantime.