comments

Read each file in full, then classify every comment as load-bearing or noise. Remove comments that restate identifier names or translate the next line into English, rewrite vague ones, and keep comments documenting non-obvious invariants or design rationale.

Good comments capture what code cannot express: design rationale, intent, constraints, and interface contracts. They sit at a higher abstraction level than the code, explain why rather than what, and survive implementation refactors without needing changes.

Refactor when a comment is needed to explain what code does rather than why. Prefer better naming, extracting a named function, or restructuring so the intent is obvious, then delete the comment or reduce it to a one-liner explaining why.

The principles apply to any language, but the examples and conventions target Rust, including module docs, doc comments on structs and fields, and verification via cargo check. Equivalent build checks can substitute in other ecosystems.

Keep comments documenting non-obvious invariants like ordering or saturation behavior, explanations of why a design decision was made, constraints not visible in types such as units or null semantics, and interface comments describing full behavior contracts.