/review - Code Review Checklist

A concise checklist distilled from CLAUDE.md for reviewing leanSpec code.

Imports

• All imports at file top — no lazy imports inside functions
• No confusing renames — use qualified access (x25519.X25519PublicKey)
• from __future__ import annotations in every file

Type Annotations

• Never quote annotations when from __future__ import annotations is present
• Prefer narrow domain types (Bytes32, PeerId, RequestId) over raw bytes
• Complete type hints on all function signatures

Code Style

• Line length: 100 characters max
• Google docstring style
• No example code in docstrings — unit tests serve as examples
• No section separator comments (# ====, # ----)
• Module-level constants use docstrings, not comments

Documentation

• Never use explicit function or method names in docs — names change
• Write short, scannable sentences — one idea per line
• Use bullet points or numbered lists for multiple items
• Never remove existing documentation unless directly invalidated by a code change

Testing

• Full equality assertions — assert the whole object, not individual fields
• Descriptive test names explaining the scenario
• Use pytest.raises(ExceptionType, match=r"...") for error tests
• Boundary values derived from source constants, never hardcoded

Architecture

• No backward compatibility code — no shims, aliases, or re-exports
• No unnecessary abstractions — inline is often better for spec code
• Simplicity over abstraction — readers should understand top-to-bottom
• SSZ types: domain-specific names (Attestations) over generic (List4096)

Before Committing

just fix    # Auto-fix lint, formatting, and markdown
just check  # Verify all checks pass