Code review guidelines

Agree on how the team reviews code - what to check and how to give feedback.

Engineering


Owner

@mention the owner

Last reviewed

Why we review

Two or three sentences: why your team reviews code. For example, to find problems early, to share knowledge and to keep the code easy to change.

For authors

  • Keep the change small, with one purpose
  • Write a description: what changes, why, and how you tested it
  • Review your own change before you ask others
  • Add or update the tests
  • Check that the automated checks pass
  • Ask for a review from who must review, for example a person who knows this code
  • A rule for your team

For reviewers

  • Answer a review request within a time, for example one working day
  • Read the description first, so that you know the purpose of the change
  • Use the questions in the table below
  • Say which comments the author must fix and which are only suggestions
  • Run the change yourself when the risk is high
  • A rule for your team

What to look for

Area

Questions to ask

Correctness

Does the code do what the description says? What happens with empty, wrong or very large input? Does it handle errors?

Design

Is this the right place for the change? Is there a simpler way? Does it repeat code that already exists?

Tests

Do the tests cover the new behavior and the edge cases? Does a test fail if the code breaks?

Readability

Can a new team member understand the code? Are the names clear? Do the comments say why, not what?

Security

Does the code check user input? Are secrets kept out of the code and the logs? Does it respect permissions?

Another area, for example performance

The questions to ask for this area

How to comment

✅ Do

  • Comment on the code, not on the person
  • Explain why, and suggest a fix
  • Ask a question when you are not sure
  • Say when something is done well

🚫 Do not

  • Use sarcasm or harsh words
  • Ask for changes that are only your personal style
  • Leave a review without an answer for days
  • Continue a long discussion in comments: talk to the author instead

When to approve

Approve when the change makes the code better and has no problem that the author must fix. A change does not have to be perfect.

Your team's rules: for example, how many approvals a change needs, and who can merge it.

allanswered knowledge management