Skip to content

Remove redundant explanatory Rust prose #281

Description

@Teakowa

Goal

Remove explanatory Rust prose that the #278 code-as-expression audit established is unnecessary for understanding the implementation, so source files remain readable through their names, types, modules, APIs, and control flow rather than through parallel prose maps.

Context

Audit #278 performed file-by-file header/comment ablation across the manually maintained production Rust surface and found no code-structure blocker: ordinary ownership, pipeline, responsibility, and execution summaries were classified as removable prose because the code already expresses that information.

Keeping that prose after proving it unnecessary adds stale-context and maintenance risk for both humans and coding agents.

Scope

  • Remove file/module headers and implementation comments that merely describe ownership, module purpose, pipeline stages, neighboring responsibilities, or obvious execution flow already discoverable from the code.
  • Remove stale or transient source commentary encountered in the audited removable-prose surface.
  • Preserve only comments/Rustdoc that carry information not reasonably expressible in code, such as external compatibility constraints, correctness/safety invariants, provenance/evidence, or real consumer-facing public contracts.
  • Re-check each affected file after removal; if a file becomes unclear without the prose, stop treating that prose as cleanup and identify the bounded code-structure defect instead.

Non-goals

  • Reducing comment count as a metric.
  • Removing useful public API Rustdoc or external contract/invariant documentation.
  • Changing behavior, ownership, crate boundaries, or public APIs.
  • Unrelated refactoring, renaming, or formatting cleanup.

Acceptance criteria

  • Redundant ownership/pipeline/module-purpose/execution-flow prose identified by the Audit final Wright structural convergence readiness #278 audit is removed from production Rust sources.
  • No retained source comment exists solely to explain structure or behavior already apparent from the implementation.
  • Retained comments have a concrete external contract, invariant, safety, compatibility, provenance, or consumer-facing documentation purpose.
  • The implementation remains understandable without explanatory headers and existing required repository gates remain green.

Dependencies / ownership

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions