Reviewing

Reviewing#

This page defines the canonical review rules for FRIDOM.

Purpose#

Code review should focus on correctness, regressions, API stability, missing verification, and maintainability risks.

The goal of review is not to restyle code. The goal is to identify concrete problems, uncertainties, or gaps that matter for the project.

Review priorities#

Review findings should be prioritized in this order:

  1. correctness bugs

  2. behavioral regressions

  3. public API breakage

  4. missing or insufficient tests

  5. documentation mismatches

  6. maintainability or structural risks

Expected review behavior#

A review should:

  • focus on concrete findings supported by the code or documentation

  • prefer evidence over speculation

  • consider tests and documentation as part of expected behavior

  • account for the repository architecture and lazypimp export rules when relevant

  • distinguish clearly between definite issues and open questions

A review should not:

  • focus primarily on formatting or personal style

  • propose broad rewrites when a narrow finding is sufficient

  • report speculative issues without a clear basis

  • ignore missing tests or missing documentation when behavior changes

What counts as a finding#

A finding should identify a concrete problem, risk, or missing verification step.

Examples include:

  • code that appears incorrect

  • behavior that no longer matches tests or documentation

  • a public symbol added without the required lazy export registration

  • a new behavior with no corresponding tests

  • a user-facing change without documentation updates

Output structure#

Reviews should present findings first.

Each finding should include:

  • the affected file and relevant lines when available

  • a short statement of the issue

  • a brief explanation of the risk or likely impact

After findings, a review may include:

  • open questions or assumptions

  • a brief summary of overall risk

  • remaining testing gaps

If no findings are identified, state that explicitly and mention any remaining uncertainty or verification gaps.

Do not#

  • do not lead with a high-level summary before presenting findings

  • do not hide important issues inside general commentary

  • do not treat style-only preferences as high-priority findings

  • do not ignore tests, docs, or package export structure when reviewing changes