---
name: coding-quality
when: '编码质量, 代码规范, 代码评审, 代码质量, 重构, over-engineering, 过度设计, 代码异味'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-pattern-coding-quality
asset_kind: pattern
lifecycle_status: active
owner_mechanism_id: mc-general-pattern
authority: supporting
routes:
  - '*'
primary_triggers:
  - 编码质量
  - 代码规范
  - 代码评审
  - 代码质量
  - 重构
  - over-engineering
  - 过度设计
  - 代码异味
priority: P2
specificity: 3
version: 1.1.0
last_reviewed: '2026-06-01'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
stages: ["编码与单元测试"]
---

## 决策规则
- 50 行能解决的问题禁止写 200 行；禁止为单次使用场景过度设计
- 每行代码变更必须可追溯到任务卡片中的显式需求，禁止"顺手"重构相邻代码
- 实现记录必须显式声明业务入口集成状态（菜单/路由/权限）
- Bug 修复必须针对根因，禁止在破损代码上叠加 workaround
- 方法必须按业务步骤拆分为单一职责的私有方法
- 新增/修改类必须文档化业务职责、边界和关键协作者
- 仅在"非显而易见"的关键行添加注释说明 why，禁止对简单赋值加噪声注释
- 方法长度不超过 80 行，超过时拆分为子方法
- 方法参数不超过 5 个，超过时封装为请求对象
- 单个类职责单一（SRP），超过 500 行的类应考虑拆分
- 条件嵌套不超过 3 层，超过时使用卫语句、策略模式或 Optional 链重构
- 禁止使用魔法数字，必须提取为命名常量或枚举

## 验收项
- [AC-01] 代码变更可追溯到任务需求
- [AC-02] 业务入口集成状态已声明
- [AC-03] Bug 修复针对根因而非 workaround
- [AC-04] 无过度设计（50行能解决的不写200行）
- [AC-05] 方法不超过 80 行
- [AC-06] 参数不超过 5 个
- [AC-07] 嵌套不超过 3 层
- [AC-08] 无魔法数字
