Code Review

Code review is a required step in the development workflow. All changes to shared branches must be reviewed before merging.

The goal of code review is to maintain code quality, share knowledge across the team, and ensure that changes align with project architecture and engineering standards.

Code reviews are conducted through GitHub pull requests.

Objectives

Code reviews help ensure that:

• Code is correct and functions as intended
• Changes follow project architecture and coding standards
• Security and reliability concerns are identified early
• Code remains readable and maintainable
• Knowledge is shared across the engineering team

Code review is a collaborative process focused on improving the codebase rather than criticizing individuals.

Pull Request Requirements

Before requesting review, a pull request should meet the following criteria:

• The branch is up to date with main
• CI checks pass successfully
• The change is scoped to a clear purpose
• The pull request title follows the Conventional Commits standard

The pull request description should:

• Include a link to the related issue or discussion
• Explain what the change does
• Explain why the change was made
• Provide any relevant implementation details

Additionally:

• Documentation has been updated where applicable
• Code has been formatted and linted
• Relevant tests have been added, and all tests pass
• Appropriate comments have been added to clarify complex or non-obvious logic
• AI-generated code has been thoroughly reviewed to ensure accuracy and correctness

If the change is complex, additional context such as screenshots, logs, or examples may be helpful for reviewers.

Pull Request Size

Pull requests should remain reasonably sized to make reviews efficient and effective.

Recommended guidelines:

• Prefer small, focused pull requests
• Avoid bundling unrelated changes
• Break large work into smaller incremental PRs when possible

Large pull requests increase review time and the likelihood of missed issues.

What Reviewers Should Evaluate

Reviewers should focus on areas that impact correctness, maintainability, and consistency.

Key review considerations include:

Correctness

• Does the code behave as intended?
• Are edge cases handled appropriately?
• Are error conditions properly managed?

Architecture

• Does the change align with the project architecture?
• Are responsibilities clearly separated?
• Are new abstractions justified?

Readability and Maintainability

• Is the code easy to understand?
• Are variable and function names clear?
• Is the logic straightforward and maintainable?

Testing

• Are appropriate tests included?
• Do existing tests still pass?
• Does the change introduce any untested behavior?

Security

• Are inputs validated where necessary?
• Could the change introduce security risks?
• Are secrets or sensitive data handled correctly?

Performance

• Does the change introduce unnecessary computation or queries?
• Are potentially expensive operations handled appropriately?

Providing Review Feedback

Feedback should be constructive, specific, and respectful.

When leaving comments:

• Explain the reasoning behind suggestions
• Offer alternatives when possible
• Distinguish between required changes and optional suggestions

Helpful comment examples include:

• Consider extracting this logic into a helper function to improve readability.
• This query runs inside a loop and may affect performance with larger datasets.
• Could we add a test for this edge case?

The goal of review comments is to improve the implementation and share knowledge.

Responding to Review Feedback

Authors should review comments carefully and respond constructively.

Recommended practices include:

• Address requested changes promptly
• Reply to comments to clarify implementation decisions
• Mark conversations as resolved once addressed
• Update the pull request with additional commits as needed

Code review should be an iterative process leading to an improved final implementation.

AI-Assisted Review Tools

AI tools such as GitHub Copilot and OpenAI Codex may provide automated suggestions during pull requests.

These suggestions can highlight potential issues, but they should always be reviewed by engineers.

AI feedback should be treated as advisory input, not an authoritative review.

Approval and Merge

A pull request may be merged once:

• Required automated checks have passed
• At least two reviewers have approved the changes
• The CODEOWNERS have approved the changes
• All conversations have been resolved

Once merged, the feature branch should be deleted.

Summary

Code review is a core engineering practice that helps maintain quality, improve collaboration, and ensure long-term maintainability of the codebase.

By keeping pull requests focused, reviewing changes thoughtfully, and collaborating constructively, the team can maintain a high standard of engineering quality.