Developer docs
Developer docs
Breadcrumbs

Code Reviews

Last Updated: July 15, 2026

A code review is a peer review before merging. The goal is to improve code quality, catch bugs or issues, and ensure correctness. Code reviews can also be an avenue for mentoring and knowledge sharing. This document covers best practices for conducting a thorough review and writing effective comments.

Golden rule

Critique the code, not the author.

Characteristics of a good review

  • Actionable — comments lead to a clear next step

  • Timely — review promptly so others aren't blocked

  • Respectful — professional and constructive tone

  • Thorough — covers functionality, quality, tests, and compliance

Standards

  • Code doesn't need to be perfect to be approved — maintain overall code health without impeding delivery

  • Personal preference is non-blocking — focus on design, functionality, and compliance

  • Try to review in a timely manner; ask that large PRs be broken up rather than taking longer to review

  • Write comments that are actionable and professional

Focus areas

Functionality

Does the code do what it's supposed to do? Are edge cases handled correctly? Are all requirements met?

Compliance

vets-api has a set of rules and conventions. See the Platform code review guidelines for PR standards and process.

Quality

Is the code readable and maintainable? Does it add unnecessary complexity or duplication? Is there a design pattern that could be applied?

Tests

Is the test coverage adequate? Do the tests cover edge cases? Will the tests actually fail when the code is broken? Are the tests readable and maintainable?

Performance

Are there opportunities to improve performance? Is the implementation efficient for what it's doing?

Security

Are there any potential security vulnerabilities? Are authentication and authorization mechanisms implemented correctly? Is there a PII exposure risk?

Steps to a review

  1. Read the pull request description. It sounds obvious, but it's a common place to cut corners. Take a mental note of the requirements.

  2. Skim the pull request at a high level. The goal is to have a broad understanding of what's in the PR before diving into details.

  3. Review the primary parts of the pull request:

    • Look for functional correctness

    • Look for high-level quality issues: readability, maintainability, duplication, complexity

    • Look for testing coverage and quality issues

  4. Review the entire pull request thoroughly:

    • Look for compliance issues

    • Look for potential bugs

    • Look for performance or security concerns

    • Look for edge cases — requirements and test coverage

    • Look for smaller quality issues

  5. Read comments from other reviewers (including Copilot). Review comments for correctness and ensure they are appropriately addressed or resolved by the author.

  6. Add your own comments where appropriate.

Copilot comments

Copilot has limited context and is sometimes incorrect. Copilot and humans often catch different things: Copilot catches small mistakes related to functionality; humans catch rule violations and maintainability or readability issues.

If a Copilot comment is incorrect, reply explaining why and resolve the comment. If a Copilot comment is correct but unaddressed, ask the author: "Please address this Copilot comment."

Comment best practices

Good comments are actionable, useful, professional, and respectful.

Tag the author

Start a comment with a mention using the author's GitHub handle. This can greatly speed up communication. Only one tag is needed per tranche of review comments or replies. For longer conversations, move to Slack or a call.

Labeling

Prefacing your comment with a label is not required, but it effectively communicates intent and severity. Suggested labels:

Label

Meaning

Trivial

Minor, non-blocking, optional

Suggestion

Improvement; may be blocking or non-blocking

Blocking

Requires update before approval

Any label that communicates intent is acceptable: Nit, Optional, FYI, Consider, etc. See the “Good comment examples” section below for usage.

Writing meaningful comments

  • Offer guidance or suggestions

  • Explain why, not just what

  • Reference reasoning or relevant standards

  • Use courtesies like please and consider

  • Assume competence and goodwill

Questions are meaningful comments too. For example: "Does this log context contain PII?" or "Is XYZ a viable alternative?" — but keep the focus on the code, not the author. Asking "Why did you approach it this way?" can also educate both parties and sometimes reveals a better solution worth documenting with a code comment.

LGTM is an acceptable comment for simple pull requests, such as adding a feature flag or updating documentation. You don't need to write a comment just to write a comment.

Depersonalize comments

Tone is difficult to convey in text. One way to avoid harsh or contentious-sounding comments and defensive replies is to avoid using "you" or "I" — make the comment about the code, not the author or your own preferences. This isn't a rule, only a suggestion to prevent conflict.

Good comment examples

  • Trivial: consider a more concise variable name

  • Issue: this log context might have PII — can you reduce the context to only what's needed for debugging?

  • Suggestion (blocking): use find_in_batches for improved memory consumption

  • Optional: consider using memoization to increase readability of #update

  • FYI (blocking): this method is deprecated, XYZ is the suggested alternative

  • Avoid default_scope because it hides behavior and could introduce bugs — use explicit scopes instead

  • Blocking: please update XYZ spec to follow the feature toggle test conventions

  • Issue: this class may be a duplicate of XYZ — can you use XYZ?

Bad comment examples

  • Make this name better

  • You shouldn't do XYZ. I would do ABC.

  • FYI: You can't do this

  • Explain this to me

  • You should write a comment, because this class isn't easy to read

  • Please fix this so it's more readable

  • Why did you do it this way?

  • I wouldn't do it that way

Help and feedback