Code Quality Way¶
Source: hooks/ways/softwaredev/code/quality/quality.md
Frontmatter
| Field | Value |
|---|---|
description |
code quality, refactoring, SOLID principles, code review standards, technical debt, maintainability |
vocabulary |
refactor quality solid principle decompose extract method responsibility coupling cohesion maintainability readability idioms ecosystem invariant |
pattern |
solid.?principle|refactor|code.?review|code.?quality|clean.?up|simplify|decompos|extract.?method|tech.?debt |
refire |
0.2 |
macro |
append |
scope |
agent, subagent |
requires |
[Read, 'Bash(awk:)', 'Bash(dirname:)', 'Bash(file:)', 'Bash(git:)', 'Bash(grep:)', 'Bash(head:)', 'Bash(sort:)', 'Bash(wc:)'] |
scan_exclude |
.md$|.lock$|.min.(js|css)$|.generated.|.bundle.|vendor/|node_modules/|dist/|build/|pycache/ |
Quality Flags — Act on These¶
| Signal | Action |
|---|---|
| File > 500 lines | Propose a split with specific module boundaries |
| File > 800 lines | Flag as priority and propose the split. Split when asked. |
| Function > 3 nesting levels | Extract inner logic into named helper functions |
| Class > 7 public methods | Decompose — likely violating Single Responsibility |
| Function > 30-50 lines | Break into steps with descriptive names |
When the file length scan (macro output) shows priority files, call them out explicitly before proceeding with the task.
Ecosystem Conventions¶
- Don't introduce patterns foreign to the language/ecosystem
- Examples to avoid:
- Rust-style Result/Option in TypeScript
- Monadic error handling where exceptions are standard
- Custom implementations of what libraries already provide
Common Rationalizations¶
| Rationalization | Counter |
|---|---|
| "Splitting this file would make it harder to follow" | A 900-line file is already hard to follow. Split at natural seam lines. |
| "There's no good place to split" | When no split point exists, the code is too tightly coupled, and that is worth fixing. |
| "I'll refactor later" | The file will only grow. Propose the split now, while the logic is fresh. |
What to Enforce¶
Add a validation, such as a lint rule, an assertion, a schema constraint or a CI check, only when breaking it is a real defect that someone would eventually hit. A useful check catches a real failure: a reference to something that does not exist, a state the code cannot reach, a contract that breaks without an error. A rule such as "every page must have exactly three links" can be consistent and always pass, yet it catches no bug and still costs maintenance. An agent that maintains the checks keeps such a rule alive indefinitely, so nobody notices that it was never worth adding. Before adding a check, name the defect its failure would represent. If you can't, don't add it.
See Also¶
- code/quality/integration(softwaredev) — a change integrates into the whole file; forbidden patch moves, the class sweep
- code/testing(softwaredev) — quality requires test coverage
- code/errors(softwaredev) — error handling is a quality signal
- tooling(softwaredev) — encode enforced conventions in tooling
- standards(documentation) — standards define quality expectations
- code/quality/edit-safety(softwaredev) — edit the source of generated output; files someone else is editing