3.1 KiB
name, description
| name | description |
|---|---|
| refactor-for-review | Producing small, single-concern, reviewable changes. Use when refactoring, cleaning up, restructuring, decomposing, or preparing a change for PR, especially in this multi-contributor AI-assisted codebase that is prone to sprawl diffs. Covers one-concern-per-commit, extracting helpers without widening scope, not bundling unrelated edits, decomposing oversized activities, comment hygiene, and a pre-handoff self-review checklist. |
Refactor for Review
This is a multi-contributor, AI-assisted codebase, and the dominant failure mode is the sprawl diff: a one-line intent that touches thirty files. The goal is a change a reviewer can verify in one sitting. Cleaner structure that makes the next change easier is the win, not lines added.
One concern per change
- A commit/PR does one thing. A bug fix is not also a rename is not also a reformat. If you spot an unrelated improvement mid-change, leave it or capture it separately; do not fold it in.
- When the working tree has bundled two changes, separate them with the copy-affected-files-aside, reset, re-apply one concern, restore the rest pattern, not by committing the tangle.
- Refactor and behavior change do not ride together. A pure refactor must not alter behavior; a behavior change should not drag a refactor along. If both are needed: two commits, refactor first.
Keep the diff narrow
- Extract a helper to remove real duplication or to name a concept, not to chase abstraction. Three-plus copies, or a block that needs a name to be understood: extract. Two similar lines: leave them.
- No "while I'm here" scope creep. A signature or type change that ripples to many call sites is its own PR: map every caller first, update them in one topological pass, and land it separately, not as a rider on a feature.
- Match the surrounding code: comment density, naming, idiom. The diff should read like the file, not like a different author.
Decompose oversized units
An activity or function that has outgrown one screen of responsibility (multiple unrelated state machines, or a file far larger than its siblings) is a decomposition candidate. Extract a cohesive sub-responsibility into its own unit, as a standalone behavior-preserving refactor, verified on its own, never mixed into a feature change.
Comments earn their place
Comments explain why: an invariant, a defense, a past incident, a non-obvious constraint. Never what the next line already says. Delete narration, phase-marker comments ("now we loop over..."), and restated function names. If a comment and the code it sits on say the same thing, the comment is the thing to cut.
Self-review before handoff
- The change does exactly one thing; nothing unrelated rode along.
- Refactor and behavior change are not mixed in one commit.
- No "while I'm here" creep; rename/signature ripples are split out.
- Extractions remove real duplication or name a real concept, not speculative abstraction.
- New comments say why, not what; no narration or phase markers.
- A reviewer can understand the diff without running it.