Readability Sweep — Three Passes
Code must read through its names, not through narration. Run the passes in order, report per pass. Scope: application source directories only — leave tests, config, and vendor code alone unless explicitly included.
Pass A — Comments
- Find every inline
// and /* */ comment in scope.
- Apply per comment:
- What-comment (restates the next line) → delete.
- Genuine why (race condition, idempotency gate, security rationale, external quirk, legal constraint) → lift into the enclosing method PHPDoc/docstring, then delete the inline form.
- Commented-out code → delete outright.
- Bare
// placeholders and trailing data annotations → delete; move rationale to class doc if it matters.
- Class-level doc blocks always stay. Method-level docs only where they carry a why or a non-obvious contract.
Pass B — Extract Method
- Inside each method, find self-contained blocks of 4+ lines that take input → transform → produce one output.
- Extract each into a
private method with an intent name — the name states what comes out, not how (priorComposites, buildRequestLine, advanceStatus).
- Do NOT extract — over-extraction reads worse than inline code:
- guard clauses and early returns
- single statements or simple assignments
- blocks mutating two or more enclosing-scope locals
- Keep paired classes symmetric: if two sibling drivers/paths share a shape, give both the same extractions.
Pass C — Naming
- For every class and public method in scope: read what it actually does, then judge the name against it.
- Enforce the house rules:
- class names carry type suffixes (
Controller, Job, Service, Event, Listener, Factory)
- queued classes carry the
Job suffix; trigger-listeners are {Verb}On{Event}Listener
- plain services use intent-named primary methods (
check, create, process, store) — never handle(), which is reserved for framework contracts
- enum cases are
ALL_CAPS_SNAKE_CASE
- Where a better name exists, propose current → suggested with a one-line justification. Apply renames only after the user picks; a rename is never silent.
- Renames rot static-analysis baselines (entries embed symbol + path). After any applied rename, flag that the baseline needs regenerating.
Post-flight
Run the project's formatter and full test suite. Both must be clean before reporting.
Output Contract
Per pass: files touched and a compact change list (Pass A: comments deleted/lifted; Pass B: methods extracted with names; Pass C: renames proposed vs applied). Then: formatter + test results, and any baseline-regeneration flag. No essays.
1---2name: readability-sweep3description: Three-pass readability cleanup of application source: remove inline comments, extract cohesive blocks into intent-named private methods, and challenge every class and method name. Use whenever the user says "readability sweep", "no inline comments", "remove comments", "check naming", "make the code readable", "extract private methods", or asks to scan the project for readability violations. Edits allowed. Scope is application source only (not tests/config) unless told otherwise. Runs lint and the full test suite after changes.4---56# Readability Sweep — Three Passes78Code must read through its names, not through narration. Run the passes in order, report per pass. Scope: application source directories only — leave tests, config, and vendor code alone unless explicitly included.910## Pass A — Comments11121. Find every inline `//` and `/* */` comment in scope.132. Apply per comment:14 - **What-comment** (restates the next line) → delete.15 - **Genuine why** (race condition, idempotency gate, security rationale, external quirk, legal constraint) → lift into the enclosing **method PHPDoc/docstring**, then delete the inline form.16 - **Commented-out code** → delete outright.17 - **Bare `//` placeholders and trailing data annotations** → delete; move rationale to class doc if it matters.183. Class-level doc blocks always stay. Method-level docs only where they carry a why or a non-obvious contract.1920## Pass B — Extract Method21221. Inside each method, find self-contained blocks of **4+ lines** that take input → transform → produce one output.232. Extract each into a `private` method with an **intent name** — the name states what comes out, not how (`priorComposites`, `buildRequestLine`, `advanceStatus`).243. **Do NOT extract** — over-extraction reads worse than inline code:25 - guard clauses and early returns26 - single statements or simple assignments27 - blocks mutating two or more enclosing-scope locals284. Keep paired classes symmetric: if two sibling drivers/paths share a shape, give both the same extractions.2930## Pass C — Naming31321. For every class and public method in scope: read what it actually does, then judge the name against it.332. Enforce the house rules:34 - class names carry type suffixes (`Controller`, `Job`, `Service`, `Event`, `Listener`, `Factory`)35 - queued classes carry the `Job` suffix; trigger-listeners are `{Verb}On{Event}Listener`36 - plain services use intent-named primary methods (`check`, `create`, `process`, `store`) — never `handle()`, which is reserved for framework contracts37 - enum cases are `ALL_CAPS_SNAKE_CASE`383. Where a better name exists, propose current → suggested with a one-line justification. Apply renames only after the user picks; a rename is never silent.394. **Renames rot static-analysis baselines** (entries embed symbol + path). After any applied rename, flag that the baseline needs regenerating.4041## Post-flight4243Run the project's formatter and full test suite. Both must be clean before reporting.4445## Output Contract4647Per pass: files touched and a compact change list (Pass A: comments deleted/lifted; Pass B: methods extracted with names; Pass C: renames proposed vs applied). Then: formatter + test results, and any baseline-regeneration flag. No essays.
digitaldreams