Rust Maintainability

Use this checklist to review Rust changes without flattening every preference into a separate reviewed rule file. Some checklist items already have durable rule pages in Rust API And Crate Shape Rules; other items are narrower prompts that should stay here until they prove reusable enough to promote.

Core Maintainability

• Working code is not enough; the crate should be easy to understand, audit, extend, and use.
• Prefer obvious, boring, well-factored code over clever abstraction.
• Prefer direct implementation code over framework-shaped code until the framework pays for itself.
• Keep concepts coherent.
• A module should own one recognizable idea.
• Do not use a module as a bucket for loosely related helpers.
• Prefer small functions with meaningful names.
• Prefer narrow structs that own one coherent concept.
• Prefer simple enums for commands and state transitions.
• Prefer named locals when parsing, rendering, or side effects need auditability.
• Avoid broad context objects.
• Avoid callback-heavy control flow.
• Avoid wrappers that exist only to hide one line of code.
• Make side effects explicit in names, call sites, and docs.
• Avoid vague docs.
• Avoid generic examples.
• Avoid unnecessary wrappers.
• Avoid over-commenting trivial code.
• Avoid broad modules.
• Avoid examples that only prove a function can be called.

Public API Shape

• Keep public API shape intentional.
• Do not preserve accidental development-era compatibility in pre-release crates.
• Every public item should have a clear owning module.
• Public error enums should be #[non_exhaustive] unless exhaustive matching is intentional.
• Error types should implement Debug, Display, and std::error::Error when they cross a public or reusable boundary.
• Error Display output should be human-oriented and actionable.
• Do not format errors with Debug in their Display implementation.
• Public types should implement Debug unless doing so is unsafe, misleading, or exposes confidential material.
• Public APIs should not leak dependency types unless dependency integration is the point of the API.
• Panics in public APIs should represent contract violations, not ordinary fallible conditions.
• Document exact panic preconditions when a public API can panic.
• Use debug_assert! for internal invariants that should be checked during development without becoming ordinary runtime error handling.
• Prefer inherent constructors or trait implementations for construction.
• Prefer regular functions over associated functions when the type name is incidental to the operation.
• Use builders when many optional fields or cross-field validation would make constructors hard to read.
• Builder build methods should validate cross-field invariants and return errors when construction can fail.

Crate Roots, Modules, And Re-exports

• Avoid giant crate roots.
• The crate root should teach the crate.
• The crate root should expose the primary path.
• The crate root should point to deeper modules.
• Public facade crates should re-export intentionally.
• Avoid glob re-exports in public facades.
• Use #[doc(inline)] when a re-export is the canonical path readers should land on.
• Put the main concept first.
• Reading order should follow execution order or conceptual dependency order.
• Keep helpers near the code that uses them unless they are independently important concepts.
• Prefer caller-before-callee order when it improves top-to-bottom reading.
• Avoid mod.rs unless there is a strong reason.
• Prefer feature-oriented modules and named files.
• Prefer name.rs over mod.rs for module roots unless local convention or tooling gives a strong reason otherwise.
• Directory-root modules should usually act as tables of contents.
• Directory-root modules should usually re-export child modules rather than own original logic.
• Prelude modules should only re-export.
• Avoid #[path] unless generated code or platform layout makes it the clearest option.
• The public API should be browseable from the file layout.
• Avoid inline modules except for tests, preludes, and generated code.
• Do not split files into a maze of tiny modules.
• Do not default to pub(crate).
• Use pub only for intentional crate-root or public library API.
• When an item becomes visible outside its module, its name and docs should make ownership obvious.

Rustdoc And Written API Contracts

• Treat Rustdoc as part of the API, not decoration.
• Start public item docs with a concise sentence that says what the item does or returns.
• Prefer prose for argument docs; avoid parameter tables unless the API truly needs tabular reference.
• Write docs for non-linear readers.
• Someone may land on any module, type, example, or guide first.
• Cross-link docs when links improve auditability.
• Document planned behavior as current scope or future work.
• Do not describe unimplemented behavior as available API.
• Run a bounded Rustdoc quality pass when crate-root teaching, item contracts, example placement, and README/Rustdoc/example alignment need to be checked together.
• Run a source-explanation pass when internal Rust code also needs to teach its system map, domain fundamentals, implementation rationale, invariants, and edge paths.
• Compare nearby crates accurately and charitably.
• Explain fit, scope, and tradeoffs instead of claiming universal superiority.
• Prefer direct ownership and boundary statements over apologetic design justifications.
• Markdown docs should hold material that does not fit in Rustdoc or README.

Tests And Evidence

• Tests should prove contracts, not implementation trivia.
• Tests should prove user-visible contracts and local invariants.
• Good tests make the maintenance question obvious.
• A reader should be able to tell what a user or future maintainer would notice if the behavior broke.
• Unit tests should cover local logic.
• Co-locate unit tests with the module behavior they prove.
• Integration tests should cover public behavior across module boundaries.
• Use integration tests when a unit test would hide the boundary being exercised.
• Doctests should cover public examples that can compile without fragile environment assumptions.
• Bug fixes should include regression tests unless the issue explains why that is impractical.
• Test error behavior, invalid input, cancellation, drop, cleanup, and boundary conditions.
• Prefer deterministic tests over tests that depend on timing or external state.
• Terminal behavior needs deterministic fixtures or testkit support before claims are broadened.
• Parser tests should use realistic samples.
• Parser tests should cover recognized shapes and safe degradation.
• Parser tests should not be broader than the parser's real contract.
• Parser recovery tests should cover malformed, truncated, unsupported, and mixed input when those cases are part of the contract.
• Navigation and scroll tests should cover boundary behavior.
• Command construction tests should prove both construction and display behavior.
• Policy tests should cover allowed, denied, redacted, and fallback behavior when policy affects output.
• Query, request, or correlation tests should cover unrelated input, late replies, timeouts, and unmatched responses when the API routes asynchronous replies.
• Drift tests should keep support claims, fixtures, docs, examples, and API paths aligned when the project has a registry or coverage inventory.
• Conversion and default tests should cover invariants encoded by coordinate, mode, selector, ID, or protocol value types.
• Avoid tests that require a real external repository, service, or terminal unless the behavior cannot be validated another way.
• Prefer behavior-oriented test names.
• Avoid test names that only repeat the function under test.
• Use fuzzing or property tests for parsers, formatters, protocol decoders, state machines, and untrusted input.

Performance And Async Behavior

• Add benchmarks where performance claims, hot paths, or allocation behavior matter.
• Document blocking behavior, allocation expectations, and important performance constraints when callers must plan around them.
• Do not make performance claims without evidence.
• Avoid unnecessary allocations in hot paths.
• Async code that can run for a long time should yield or otherwise make scheduling expectations clear.

CI, Lints, And Unsafe Code

• Treat CI as part of the library's public quality bar.
• CI should check the same commands maintainers are expected to run locally.
• Prefer fast deterministic CI jobs with clear failure modes.
• Keep required checks strict enough that drift does not accumulate.
• Run formatting and clippy early because they fail fast.
• Run docs as a first-class job, not only as a release task.
• Run tests with all features.
• Run important feature combinations separately.
• Run MSRV checks if the crate declares an MSRV.
• Run platform checks for every supported platform.
• Document manual validation gaps when platform behavior cannot be fully tested in CI.
• Keep slow fuzzing, long benchmarks, and exhaustive compatibility checks out of required PR CI unless they are fast and deterministic.
• Add scheduled or manual CI for expensive checks.
• Avoid noisy automation that produces dependency churn or low-signal failures.
• Use lint configuration only when it encodes a durable project rule.
• Do not enable a large pile of strict lints blindly.
• Enable stricter lints when they improve correctness, public API quality, or maintainability.
• Deny accidental unsafe code when the crate does not need unsafe.
• Keep unsafe blocks small and wrapped by safe APIs.
• Explain each unsafe block with a SAFETY: comment that states the invariant being relied on.
• Test the safe wrapper around unsafe code rather than only the unsafe internals.
• Consider linting broken Rustdoc links, bare Rustdoc URLs, unreachable public items, unused crate dependencies, unexpected cfgs, and missing debug implementations for public types.
• Use warn(missing_docs) once the API is ready for that pressure.
• Avoid lint suppressions unless they explain why the exception is correct.
• Never use lint allows as cleanup by silencing.
• Prefer #[expect] over #[allow] when the suppression should fail after the lint stops firing.
• Keep lint suppression scope as small as the exception permits.

Feature Flags And Dependency Policy

• Make feature flags additive where possible.
• Avoid features that silently change public semantics.
• Keep optional dependencies tied to clearly named features.
• Keep test-only helpers out of the normal public API; use dev-dependencies or an explicit test-util feature when downstream tests need them.
• Use grouped dependency-update automation to reduce PR noise.
• Treat semver-compatible dependency breakage as a downstream integration concern.
• Use dependency-management commands when they preserve manifest consistency better than hand edits.

Workspace And Crate Boundaries

• Prefer small shared dependency surfaces in core crates.
• Keep new code and tests inside the crate or module that owns the behavior.
• Avoid adding ad hoc modules under a root facade.
• Avoid cross-crate coupling.
• Expose shared helpers through crate-local modules unless public API is intended.
• Prefer explicit module re-exports for library APIs.
• Avoid broad public helpers, util, or common modules unless they name a user-facing concept.

Imports, Ordering, And Types

• Keep imports ordered and minimal.
• Group private imports before public re-exports.
• Keep private imports limited to traits and heavily used items whose meaning remains obvious.
• Prefer module-based grouped imports over one-import-per-line style.
• Group public items before private items when that helps readers find the API first.
• Put the titular or central item first.
• Put a type's inherent impl near the type.
• Put inherent impls before trait impls when inherent methods are the core API.
• Use judgment when file-order rules conflict.
• Prefer explicit types where clarity matters.
• Prefer standard library types that carry meaning, such as Path, PathBuf, OsStr, OsString, Duration, Instant, SystemTime, SocketAddr, IpAddr, RangeBounds, Cow, and NonZero*.
• Prefer Send + 'static errors, futures, and service handles when they cross task or thread boundaries.
• Avoid global mutable state.
• Make filesystem, network, time, randomness, process, and other host interactions injectable at a boundary when tests or alternate environments need control.
• Use generics, stored generic parameters, and trait objects deliberately. Use generics over traits for local dependency injection, generic structs when ownership is stored, and trait objects only when runtime heterogeneity or object safety is needed.

Local Style And Documentation Hygiene

• Use field init shorthand when it improves ordinary Rust readability.
• Format Rust code in doc comments when the formatter can do so consistently.
• Normalize doc attributes when the project formatter supports it.
• Group imports at module granularity when that keeps import blocks readable.
• Wrap comments and doc comments near the prose line length.
• Scope lint allows narrowly.
• Document the reason for each lint allow.
• Feature flags should match the public capability they enable.
• Feature-gated code paths need tests.
• Feature-gated docs paths need validation.
• Build docs in CI with warnings denied.
• Keep README examples, Rustdoc examples, and example directories aligned.
• Keep generated README content aligned with crate-level Rustdoc.
• Run doctests when editing public Rustdoc.
• Run feature-gated integration tests when changing feature-gated integrations.
• Lint Markdown headings, links, tables, and fenced code blocks.
• Avoid making CI flaky on external link checks.

Release Checks

• Configure docs.rs metadata intentionally.
• Validate package contents before publishing.
• Inspect included docs, examples, license files, README, and generated artifacts before release.
• Ensure changelog, version numbers, crate metadata, docs.rs config, and README support claims agree.
• Do a dry-run publish where possible.
• Tag only after the release artifact is validated.
• Prefer fewer high-signal gates over many noisy gates.
• CI should make quality cheaper, not bury maintainers in ritual.

Review Practice

• Review from the perspective of a future maintainer who did not write the code.
• Look for repeated problems across modules, not only isolated defects.
• Prefer concrete findings with file or module references and proposed fixes.
• Prioritize correctness, public API clarity, documentation truthfulness, and maintainability.
• If a module is hard to read, name the cause: concept mixing, poor ordering, hidden state, vague names, or too much abstraction.
• Read the existing code first.
• Keep edits scoped to the owning concept.
• Validate with focused checks while working and fuller checks before declaring completion.
• Call out residual gaps honestly.
• Treat code organization as technical writing for future reviewers and debuggers.
• Lead with the most salient details and let readers dig deeper as needed.
• Guide readers through file structure the way prose guides readers through sections and paragraphs.

Expression Shape

• Keep weak abstractions close to their use.
• Group related logic with whitespace.
• Treat visual blocks as paragraphs inside functions.
• Open an incremental state-building block with the state being built.
• Use early returns for non-business bookkeeping.
• Keep mutually exclusive business paths visually visible with if, else, or match when that highlights the domain rule.
• Do not mix side-effect statements and pure expressions in the same logical step.
• Keep combinator closures free of business-logic side effects.
• Prefer loops over combinators when the operation is performed for side effects.