Back to Details

code-complexity-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Complexity Audit

代码复杂度审计

Deep software design analysis based on "A Philosophy of Software Design" by John Ousterhout. Produces a Design Health Report evaluating structural and conceptual design quality — not linting or style.
基于John Ousterhout所著《软件设计哲学》（A Philosophy of Software Design）的深度软件设计分析。生成一份设计健康报告，评估结构和概念层面的设计质量——而非代码检查（linting）或代码风格。

Process

流程

  1. Read this file
  2. Read 
    references/analysis-framework.md
    for detailed checklists and scoring rubrics
  3. Scan the project structure and key files
  4. Produce the Design Health Report
  1. 阅读本文件
  2. 阅读
    references/analysis-framework.md
    获取详细的检查清单和评分标准
  3. 扫描项目结构和关键文件
  4. 生成设计健康报告

Step 1: Reconnaissance

第一步：侦查

  • List project structure (2-3 levels deep)
  • Identify language(s), framework(s), paradigm (OOP, functional, etc.)
  • Count approximate files, modules/classes, lines of code
  • Identify entry point(s) and core modules
  • Check dependency files (package.json, requirements.txt, go.mod, Cargo.toml, etc.)
  • 列出项目结构（2-3层深度）
  • 识别使用的语言、框架、编程范式（OOP、函数式等）
  • 估算文件、模块/类、代码行数的大致数量
  • 识别入口点和核心模块
  • 检查依赖文件（package.json、requirements.txt、go.mod、Cargo.toml等）

Step 2: Sampling Strategy

第二步：抽样策略

  • Always read: Entry points, core domain modules, most-imported files
  • Sample: 3-5 files from each major directory/package
  • Prioritize: Largest, most-changed (git history), most-imported files
  • Include: Public API surfaces, interfaces, error handling, tests
Aim for 15-30 representative files depending on project size.
  • 必读文件：入口点、核心领域模块、被引用最多的文件
  • 抽样范围：每个主要目录/包中选取3-5个文件
  • 优先级：体积最大、变更最频繁（git历史）、被引用最多的文件
  • 包含内容：公共API接口、接口定义、错误处理、测试文件
根据项目规模，目标选取15-30个具有代表性的文件。

Step 3: Deep Analysis

第三步：深度分析

Read 
references/analysis-framework.md
for the full framework. Evaluate across 15 dimensions:
Core Design Structure (highest weight):
  1. Module Depth — Deep (simple interface, rich functionality) vs shallow?
  2. Information Hiding — Knowledge encapsulated or leaking?
  3. Abstraction Quality — Right level? True or false abstractions?
  4. Complexity Indicators — Change amplification, cognitive load, unknown unknowns
Structural & Process (medium weight): 5. Error Handling — Defined out of existence, masked, or proliferating? 6. Naming & Obviousness — Clear mental images? Obvious code? 7. Comments & Documentation — Describe non-obvious things? 8. Consistency — Conventions followed uniformly? 9. Layering — Different layer = different abstraction? Or pass-through? 10. Strategic vs. Tactical — Design investment or quick fixes?
Deep Structural Patterns: 11. Design Investment & Evolution — Improving over time? "Design it Twice" evidence? 12. Software Trends Anti-Patterns — Getter/setter overuse, deep inheritance, forced patterns? 13. Performance-Design Relationship — Simplicity creating speed or complexity creating overhead? 14. Comments as Design Tool — Completing abstractions or afterthoughts? 15. Codebase Navigability — Zero-context newcomer can navigate from file tree alone?
阅读
references/analysis-framework.md
获取完整分析框架。从15个维度进行评估：
核心设计结构（权重最高）：
  1. 模块深度 —— 是深度模块（简单接口、丰富功能）还是浅层模块？
  2. 信息隐藏 —— 知识是被封装还是泄露？
  3. 抽象质量 —— 抽象层级是否合适？是真实抽象还是虚假抽象？
  4. 复杂度指标 —— 变更放大、认知负荷、未知的未知项
结构与流程（权重中等）： 5. 错误处理 —— 是将错误定义为不存在、被掩盖还是不断扩散？ 6. 命名与直观性 —— 能否形成清晰的心智模型？代码是否直观？ 7. 注释与文档 —— 是否描述非直观的内容？ 8. 一致性 —— 是否统一遵循约定？ 9. 分层设计 —— 不同层级对应不同抽象？还是存在透传层？ 10. 策略性 vs 战术性 —— 是长期设计投入还是快速修复？
深层结构模式： 11. 设计投入与演进 —— 是否随时间持续改进？是否有“设计两次”的实践证据？ 12. 软件趋势反模式 —— 是否过度使用getter/setter、深度继承、强制模式？ 13. 性能与设计的关系 —— 简洁性提升速度还是复杂度增加开销？ 14. 注释作为设计工具 —— 是完善抽象还是事后补充？ 15. 代码库可导航性 —— 无背景的新手能否仅通过文件树导航？

Step 4: Produce the Report

第四步：生成报告

markdown
undefined
markdown
undefined

Code Complexity Audit: [Project Name]

Code Complexity Audit: [Project Name]

Executive Summary

Executive Summary

[2-3 sentence assessment w/ letter grade A-F]
[2-3 sentence assessment w/ letter grade A-F]

Scores

Scores

[Table: each dimension scored 1-10 w/ brief justification]
[Table: each dimension scored 1-10 w/ brief justification]

Top Findings

Top Findings

Critical Design Issues

Critical Design Issues

[Most severe — actively creating complexity]
[Most severe — actively creating complexity]

Improvement Opportunities

Improvement Opportunities

[Moderate — could be cleaner]
[Moderate — could be cleaner]

Design Strengths

Design Strengths

[What the project does well — always include]
[What the project does well — always include]

Detailed Analysis

Detailed Analysis

[Per-dimension subsections w/ file/line references and code examples]
[Per-dimension subsections w/ file/line references and code examples]

Red Flags Detected

Red Flags Detected

[Reference the canonical red flags list below]
[Reference the canonical red flags list below]

Recommendations

Recommendations

[Prioritized, actionable — what to fix first and how]
[Prioritized, actionable — what to fix first and how]

Appendix: Files Reviewed

Appendix: Files Reviewed

[All files examined]
undefined
[All files examined]
undefined

Ousterhout's Design Principles

Ousterhout的设计原则

Evaluate the project against each:
  1. Complexity is incremental — small stuff accumulates
  2. Working code isn't enough — design quality matters equally
  3. Continual small investments — 10-20% of time on design improvement
  4. Modules should be deep — simple interfaces, rich functionality
  5. Common case should be simple — good defaults, minimal config
  6. Simple interface > simple implementation — callers' ease matters more
  7. General-purpose modules are deeper — avoid over-specialization
  8. Separate general-purpose and special-purpose — push specialization up/down
  9. Different layers = different abstractions — no pass-through layers
  10. Pull complexity downwards — developers suffer, not users
  11. Define errors out of existence — simplify error semantics
  12. Design it twice — consider alternatives before committing
  13. Comments describe non-obvious things — different level of detail than code
  14. Design for reading, not writing
  15. Increments = abstractions, not features
  16. Separate what matters from what doesn't
  17. Not making design better → making it worse — continuous evolution
对照以下原则评估项目：
  1. 复杂度是渐进累积的 —— 小问题会不断堆积
  2. 可运行的代码还不够 —— 设计质量同样重要
  3. 持续的小投入 —— 投入10-20%的时间用于设计改进
  4. 模块应保持深度 —— 简单接口，丰富功能
  5. 常见场景应保持简洁 —— 良好的默认值，最小化配置
  6. 简单接口 > 简单实现 —— 调用方的易用性更重要
  7. 通用模块更具深度 —— 避免过度专业化
  8. 分离通用与专用功能 —— 将专用逻辑上移/下移
  9. 不同层级对应不同抽象 —— 无透传层
  10. 将复杂度向下转移 —— 让开发者承担复杂度，而非用户
  11. 将错误定义为不存在 —— 简化错误语义
  12. 设计两次 —— 确定方案前考虑替代选项
  13. 注释描述非直观内容 —— 与代码的详细程度不同
  14. 为阅读而非编写设计
  15. 增量开发的是抽象，而非功能
  16. 区分重要与不重要的内容
  17. 不改进设计就是在恶化设计 —— 持续演进

Red Flags

危险信号

Red FlagSignal
Shallow ModuleInterface nearly as complex as implementation
Information LeakageSame design decision in multiple modules
Temporal DecompositionStructured by execution order, not information hiding
OverexposureCommon-case users must learn rare features
Pass-Through MethodForwards to another method w/ same signature
RepetitionSame nontrivial pattern in multiple places
Special-General MixtureSpecial-purpose code in general-purpose mechanisms
Conjoined MethodsCan't understand one without reading another
Comment Repeats CodeRestates what code says
Implementation in Interface DocsInterface docs describe implementation
Vague NameToo generic to convey meaning
Hard to Pick NameNaming difficulty → unclear design
Hard to DescribeNeeds long comment → bad abstraction
Nonobvious CodeBehavior unclear from quick reading
危险信号表现
浅层模块接口复杂度几乎与实现相当
信息泄露同一设计决策出现在多个模块中
时间分解按执行顺序而非信息隐藏组织代码
过度暴露普通用户必须学习罕见功能
透传方法转发至另一个签名相同的方法
重复代码相同的非 trivial 模式出现在多个地方
通用与专用混合通用机制中包含专用代码
耦合方法无法独立理解其中一个方法
注释重复代码重述代码已表达的内容
接口文档包含实现细节接口文档描述实现内容
模糊命名过于通用，无法传达含义
命名困难命名难度大 → 设计不清晰
难以描述需要长篇注释 → 抽象设计差
非直观代码快速阅读无法理解行为

Tone & Approach

语气与方法

  • Constructive — help, not tear down
  • Always include strengths
  • Specific — reference files, classes, methods, line numbers
  • Actionable recommendations w/ before/after examples
  • Context-aware — weekend prototype ≠ production system
  • Use the project's own code in examples
  • 建设性 —— 提供帮助，而非贬低
  • 始终包含优势部分
  • 具体 —— 引用文件、类、方法、行号
  • 可落地的建议，附带前后示例
  • 上下文感知 —— 周末原型 ≠ 生产系统
  • 使用项目自身代码作为示例

Adapting to Project Size

适配项目规模

  • Small (<20 files): Read everything. Concise report.
  • Medium (20-200 files): Sample. Focus on core modules.
  • Large (200+ files): Heavy sampling. Focus on architecture and public APIs. Consider one subsystem deeply vs. everything shallowly.
  • 小型项目（<20个文件）：通读所有文件，生成简洁报告。
  • 中型项目（20-200个文件）：抽样分析，聚焦核心模块。
  • 大型项目（200+个文件）：大量抽样，聚焦架构和公共API。考虑深入分析一个子系统，而非浅尝辄止所有内容。