notes/docs/professional/software-development-practices/code-review.md

# Code review practices

## Who should review?

Code should be reviewed by senior developers who understand the system being
changed.

Code can also be reviewed by more junior developers, as they can learn about the
system by comprehending the changeset, and they can spot some mistakes or
problems. However these reviewers should not be able to approve pull requests.

## What should be reviewed?

- The change should make sense to the reviewer.
- The code should meet the team's standards for maintainability.
- The changeset should be limited to the problem being solved by the pull
  request.

## Write actionable comments

[Conventional comments](https://conventionalcomments.org/)

### Comment structure

```
label [decorators]: subject

discussion

[suggestion]
```

### Tags for blocking comments

- **problem**: Something is wrong with the code that means the PR should not be
  merged.
- **question (blocking)**: Reviewer needs an explanation about part of the code
  before they understand it well enough to approve.
- **cleanup**: Some vestigial code needs to be removed before merge.
- **typo**: Fix a typo.

### Non-blocking comments

All non-blocking tags need to be decorated as **non-blocking** to make it clear
to the PR author that the comment isn't blocking approval.

- **quibble (non-blocking)**: Something is wrong with the code but it's not
  severe enough to block the PR from being merged.
- **polish (non-blocking)**: The code quality can be improved.
- **question (non-blocking)**: Reviewer needs an explanation about part of the
  code before they understand it well enough to approve.
- **suggestion (non-blocking)**: A change of any kind that improves the
  implementation or code quality, but isn't a blocking problem.