# Code Review Guidelines


- Each MR should be focused, changing only one concept at a time
- Keep MRs small - aim for under 500 lines of diff. There can be some wiggle room for cases that are hard to split
- When reviewing code, check for test coverage and suggest tests if missing
- Go through tests and think hard to see if any unit tests or group of unit tests can be replaced with a property test
- When suggesting a property test, consider cases that the property needs to falsify and whether it needs its own generator
- Business logic stays pure

## Comments

- Less is more
- If there's comments for a function, verify they're proper haddock style
- If there's comments for a function, they must only be about the contract and use instructions
- If there's comments for implementation, they should only be for exceptional cases, cases where the reader would question why something is implemented like that
- Comment style should follow minimalistic writing style

## Recording reviews

Reviews are stored as git notes under `refs/notes/review`, one note per
reviewed commit. The note header carries `branch`, `round`, `verdict`
(`approve` or `request-changes`), `previous` (sha of the last reviewed tip),
and a findings list with stable IDs (`F1`, `F2`, ...) whose `status` is
`open`, `resolved`, or `wontfix`. The body is free markdown prose.

Protocol:

1. Fetch prior results:
   `git fetch origin "refs/notes/review:refs/notes/review"`
2. Read the latest verdict and open findings for the branch:
   `scripts/review-note latest <branch>`
3. Review the branch tip per this document.
4. Write the note (header + markdown) to a file and attach it to the tip:
   `scripts/review-note write <file>`. Use `--force` only to replace a note
   on the same commit deliberately.
5. Publish: `scripts/review-note push` (plain `git push` does not push
   notes).

On a re-review after fixes: new tip, new note, `round`+1, `previous` set to
the last reviewed sha, open findings carried forward by ID, resolved ones
marked `resolved`.