Back to Details

audit-code-complexity

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Audit code complexity

代码复杂度审计

Find what is materially harder to understand, change, or verify than the problem requires.
找出那些相较于问题实际需求，在理解、修改或验证难度上显著更高的部分。

Scope

范围

Choose from the user's wording:
  • Current-state. Audit the target as it exists, regardless of when complexity was introduced.
  • Change-scoped. Report only complexity introduced or materially worsened by the named changes. Inspect surrounding code only for context.
Do not infer change scope merely because a repository has changes. If both modes are requested, report them separately. Ask only when genuine ambiguity would materially change the audit.
根据用户的表述选择审计范围：
  • 当前状态：审计目标代码的现状，不考虑复杂度是何时引入的。
  • 变更范围：仅报告由指定变更引入或明显恶化的复杂度问题。仅为理解上下文而检查周边代码。
不要仅因为仓库存在变更就推断采用变更范围模式。如果用户同时要求两种模式，需分开报告结果。仅当存在真正的歧义且会显著影响审计结果时，才向用户询问确认。

Method

方法

Inspect the target, repository instructions, callers, tests, configuration, and only the requirements or docs needed to understand behavior and constraints.
Look for:
  • unjustified indirection, wrappers, genericity, extension points, dependencies, or infrastructure
  • tangled control flow, flag combinations, implicit state, invalid states, or multiple sources of truth
  • repeated transformations, leaky types, wide APIs, hidden side effects, or unclear ownership
  • duplicated policy, scattered edits for one change, or modules with unrelated responsibilities
  • misleading names, distant cause and effect, broad mutation, dense expressions, or clever code
  • speculative guards, fallbacks, compatibility paths, or dead machinery
  • test harnesses, fixtures, mocks, or setup that make production behavior harder to understand or change
Smell names are optional vocabulary for explaining a concrete mechanism, not a checklist to exhaust or evidence of a violation. Use labels such as Feature Envy, Data Clumps, Shotgun Surgery, or Speculative Generality only when they make a finding clearer.
Include a finding only when:
  1. The code creates a concrete maintenance, comprehension, correctness, or operational cost.
  2. The claim is supported by code, usage, tests, or requirements.
  3. A simpler alternative is concrete and preserves required behavior and contracts.
  4. The benefit outweighs migration and regression risk.
Line count, nesting, complexity metrics, and unfamiliarity are clues, not findings.
Before recommending removal of a wrapper, read its callers, including tests. Check what it handles that callers would otherwise need to handle themselves. Keep it when it owns useful behavior or protects a required contract. If it only forwards a call, consider putting that call in the appropriate existing module. File size and caller count alone do not decide this.
When you find a problem, check whether the same problem occurs elsewhere in the code you were asked to audit. Report affected locations together when the same fix applies; keep cases separate when they must preserve different behavior. If you checked only part of the target, say so instead of presenting examples as a complete list.
检查目标代码、仓库说明、调用方、测试、配置，以及仅用于理解代码行为和约束的必要需求或文档。
重点关注以下问题：
  • 不合理的间接层、包装器、泛化设计、扩展点、依赖或基础架构
  • 混乱的控制流、多标志组合、隐式状态、无效状态或多数据源
  • 重复的转换逻辑、类型泄漏、过于宽泛的API、隐藏的副作用或不清晰的权责归属
  • 重复的策略逻辑、一处修改需要多处改动的情况，或承担无关职责的模块
  • 具有误导性的命名、因果逻辑分散、大范围状态变更、晦涩的表达式或“炫技式”代码
  • 投机性的防护逻辑、降级方案、兼容路径，或已废弃的无用机制
  • 导致生产环境行为更难理解或修改的测试框架、fixture、mock 或初始化逻辑
代码坏味的名称只是用于解释具体机制的可选表述，并非需要逐一核对的检查清单，也不能直接作为问题存在的证据。仅当能让发现的问题更清晰时，才使用 Feature Envy、Data Clumps、Shotgun Surgery、Speculative Generality 等标签。
仅当满足以下条件时，才将其列为审计发现：
  1. 该代码确实带来了实际的维护、理解、正确性或运维成本。
  2. 该结论有代码、使用方式、测试或需求作为支撑。
  3. 存在具体的更简洁替代方案，且能保留原有要求的行为和契约。
  4. 优化带来的收益大于迁移和回归风险。
代码行数、嵌套层级、复杂度指标以及对代码的陌生感都只是线索，而非审计发现本身。
在建议移除某个包装器之前，需查看其所有调用方（包括测试），确认它处理了哪些原本需要调用方自行处理的逻辑。如果包装器承载了有用的行为或保护了必要的契约，则应保留。如果它仅做调用转发，则考虑将该调用放入合适的现有模块中。不能仅依据文件大小或调用方数量来决定是否移除。
当发现某个问题时，需检查在要求审计的代码范围内是否还存在其他相同问题。如果修复方案通用，可将所有受影响位置合并报告；如果不同位置需要保留不同行为，则分开报告。如果你仅检查了目标代码的一部分，需明确说明，不要将举例当作完整的问题列表。

Test boundary

测试边界

Inspect tests when they establish a contract, explain intended behavior, or provide evidence for a complexity finding.
Report test-related complexity only when the test architecture creates or conceals a concrete cost. Examples include shared setup with hidden state, helper layers that obscure behavior, duplicated fixtures that encode policy in several places, test-only seams that force production indirection, or mocks that hide unclear ownership.
Do not turn this into a general review of test value, coverage, snapshots, assertions, or missing cases. When tests are the main subject, use 
test-quality-audit
instead.
当测试用于定义契约、说明预期行为，或为复杂度问题提供证据时，需要检查测试代码。
仅当测试架构产生或掩盖了实际成本时，才报告与测试相关的复杂度问题。例如：包含隐藏状态的共享初始化逻辑、掩盖行为的辅助层、在多处编码策略的重复 fixture、迫使生产代码增加间接层的仅测试用接缝，或掩盖权责不清问题的 mock。
不要将此审计变成对测试价值、覆盖率、快照、断言或缺失用例的通用评审。如果测试是主要审计对象，请使用 
test-quality-audit
。

Output

输出

Lead with a verdict, then prioritized findings. For each finding include:
  • impact and confidence
  • exact location and evidence
  • concrete cost
  • simpler alternative
  • behavior or contracts that must remain unchanged
Add justified complexity, simplification order, and validation only when useful. If no material findings exist, say so directly.
首先给出结论，然后按优先级列出审计发现。每条发现需包含：
  • 影响程度和置信度
  • 具体位置和证据
  • 实际成本
  • 更简洁的替代方案
  • 必须保持不变的行为或契约
仅在有必要时，补充说明合理的复杂度、简化的先后顺序以及验证方法。如果没有发现实质性问题，直接说明即可。

Rules

规则

  • Audit only; do not edit unless explicitly asked.
  • Prefer local simplification over rewrites.
  • Do not create an abstraction solely to remove similar-looking code; require a shared concept.
  • Preserve domain distinctions, data semantics, source of truth, identity, routing, validation, security, accessibility, and compatibility.
  • Skip formatter, linter, naming, and style nits unless they materially obscure behavior.
  • Do not present an ordinary correctness bug as a complexity or simplification finding. Report bugs, security, or performance issues only when caused or concealed by the complexity under review, and label them separately from simplification findings.
  • 仅执行审计；除非明确要求，否则不修改代码。
  • 优先采用局部简化，而非整体重写。
  • 不要仅为了消除看起来相似的代码而创建抽象；必须存在共享的概念基础。
  • 保留领域边界、数据语义、单一数据源、标识、路由、校验、安全、可访问性和兼容性。
  • 忽略格式化、linter、命名和风格类的小问题，除非它们严重影响了对代码行为的理解。
  • 不要将普通的正确性 bug 归为复杂度或简化类发现。仅当 bug、安全或性能问题是由本次审查的复杂度导致或被其掩盖时，才予以报告，且需与简化类发现分开标注。