How to Review a Pull Request Kindly and Carefully
Review a pull request by checking behavior, tests, security, readability, compatibility, and the author's context with specific comments.
Read the change in layers. First understand the intended behavior and affected users, then inspect the implementation, tests, security boundaries, performance risks, and compatibility. Use a local checkout or a focused test when the diff leaves an important question unanswered. Phrase comments around the code and its consequence: identify the condition, the possible failure, and a question or suggestion for resolving it. Mark preferences separately from required corrections. Do not ask an author to fix an issue that cannot affect this change without explaining why it belongs now. A concise review summary should state what was checked and what remains uncertain.
Understand the change first
Read the pull request description, linked issue, scope, and testing notes before commenting on individual lines. Identify the behavior that should change and what must remain stable. Inspect the diff in a sensible order: structure, core logic, error handling, tests, documentation, and configuration. A few minutes of context prevents comments that the author already solved elsewhere.
Run the relevant checks locally or inspect the continuous integration result. Test the important path yourself when possible. Look for missing tests around boundaries, permissions, empty data, time zones, and failure responses. A green check does not prove that the requirement was understood, so compare the implementation with the stated outcome.
Prioritize real risk
Comment first on bugs, data loss, security weaknesses, accessibility barriers, broken compatibility, and unclear behavior that could affect users. Explain the consequence and suggest a way to investigate. Separate required changes from optional improvements. A preference about naming should not appear as an urgent failure.
Check the change at its boundaries. What happens when a service is unavailable, a value is missing, an account lacks permission, or the user repeats an action? Review input validation and output encoding. Check logs for private data and configuration for secrets. If the change affects a regulated or high-stakes domain, confirm that the required reviewer or policy was involved.
Make comments specific and respectful
Describe the code and its effect, not the intelligence or motives of the author. """This path can send an empty identifier to the endpoint; could we validate it before the request?""" gives a clear issue. Ask a question when the intent is uncertain. Avoid sarcasm, vague commands, and comments that repeat an established project rule without explaining the relevant risk.
Do not request unrelated refactoring in a focused change unless it blocks review. Open a separate issue for useful cleanup. If the code is hard to understand, explain which future change or failure the ambiguity makes difficult. Offer an example or a reference to the local pattern.
- Use the project's review labels and severity conventions.
- Protect private customer and employee information in test data.
- Check documentation and release notes for user-facing changes.
- Re-review resolved comments instead of reopening settled preferences.
Close with a decision
Summarize remaining blockers, accepted tradeoffs, and checks you ran. Approve when the change meets the contract, even if it is not written exactly as you would write it. Thank the author for clarifying difficult parts without replacing technical feedback with praise. A review should leave the code safer and the conversation easier to continue.
Kindness and rigor support each other in code review. Clear standards, evidence, focused comments, and respect for the author create a process where people can find defects early and still feel able to ask for help when the next difficult change arrives.
Consider review timing. A small request early can save a large rewrite late, while a stream of line comments during an unfinished design can create noise. State whether the change is ready for detailed review or still seeking direction. For urgent fixes, record what was not checked and schedule the follow-up. Honest limits make approval more trustworthy than pretending every risk was eliminated.