Community编程与开发github.com

查找复杂函数

识别那些让读者难以理解的函数:它们承担了过多职责、嵌套过深、混杂不同抽象层次,或使用了过多的局部变量。

查找复杂函数 是什么?

该技能旨在系统性地识别代码库中那些因复杂度而难以维护的函数。它超越了简单的“函数太长”的判断,深入分析导致复杂性的四个核心维度:职责数量、分支路径、嵌套深度、局部变量数量以及抽象层次的混杂程度。支持用于任何可静态分析或人工审查的代码库(如 Python、JavaScript、Go、Rust 等语言的项目)。技能提供了一套可执行的操作流程:首先测量函数体(包括物理行数、有效行数、嵌套深度和局部变量数),然后评估行数背后隐藏的缺陷(职责、分支、抽象层次等),接着建议具体的重构技术(如提取方法、卫语句、扁平化数据结构、使用库函数),最后要求输出包含函数分析表和具体改进建议的结构化报告。其核心理念是:代码复杂度由下一个修改它的人承担,因此识别和降低复杂度是提高代码可维护性的关键行动。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/thomasdolash/code-audit-skills/tree/HEAD/find-complex-functions

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

查找复杂函数 是做什么的?

复杂函数要求读者记住超出其职责所需的信息。它承担了多个责任、分支嵌套分支、混杂不同抽象层次的语句,或者使用了过多的局部变量,让人难以跟踪。

长度是症状,而非缺陷。一个90行的平面调度表很容易理解;一个40行但有四个嵌套循环的函数则不然。找出要求读者记住的内容,并为那些应该独立的步骤命名。

真正的问题

复杂度的代价是由下一个修改函数的人承担的,而非编写它的人。它体现在:必须从头到尾理解才能进行的修改、在错误位置添加的分支,或者因为审阅者看到第60行就放弃了而导致幸存下来的 Bug。

一个发现不是“函数太长”。对于每个发现,描述函数体做了什么、包含了多少事情、你会提取哪些步骤,或者明确说明为什么当前形态是合理的。 一个较长的函数如果实现了一个内聚的算法,也可能是正确的。

操作流程

  1. 测量函数体,然后阅读它。 记录物理行数、有效行数(不包括空行和注释)、最大嵌套深度以及局部变量数。对于手工维护的代码,阈值如下:

    函数大小阅读难度
    20行以下理想:函数体可视为一个步骤
    20至50行正常范围
    50至80行需审查:说明各部分是否可以分离
    80行以上通常期望拆分
    200行以上高优先级复杂度发现
  2. 量化行数所代表的问题。 对于每个被标记的函数:

    • 职责。 如果需要用“并且”才能诚实描述,那么它就是两个函数。更强的信号是有两个不同的调用者、行为者或修改原因,这即是分离的接缝。
    • 分支路径。 统计 if、循环、match 分支和 catch。少量分支没问题;跨嵌套分支倍增的路径才是信号,而这正是使一个短函数变难的原因。
    • 嵌套深度。 深度会降低可接受的长度上限:随着复杂度和缩进的增加,上限会下降。通常容忍三层;超过三层应重构而非继续嵌套。同样是60行,在深度1时没问题,在深度4时就是错误的。
    • 局部变量。 超过大约7到10个,读者就无法全部记住;这本身就是一个发现。
    • 抽象层次。 在一个函数体内混合高层策略和底层解析、索引或指针操作,无论长度如何都是缺陷。 当以上统计项无法完全反映问题时,行数仍然重要:一个嵌套调用链可能只有一个语句、零个分支,但有16行必须按顺序阅读。
  3. 命名你要提取的步骤,并说明哪种技术适合。 以下四种技术承担了大部分工作:

    • 提取方法: 将嵌套块移动到一个命名辅助函数中,每个函数只负责一个关注点。
    • 卫语句和提前返回: 先拒绝无效情况,使函数体只在单层缩进中运行,而不是位于三个条件语句内部。
    • 更扁平的数据结构: 用单次遍历索引、映射或预构建列表来替代嵌套遍历。
    • 使用库函数: 当嵌套是手写算法(排序、分组、匹配)时,删除的代码就是胜利。 对于链式调用而非循环(例如 Promise、Observable 和 Pipeline),规则相同:进行组合,永远不要在另一个订阅或管道内部进行嵌套。然后说明每个辅助函数应叫什么名称,以及它将负责什么。“重构这个函数”不是一个发现,仅仅将代码行移动到新名称下也不是。如果提取的步骤仍然需要整个函数体的上下文,那它就不是一个步骤。
  4. 检查参数列表和返回形状。 参数数量过多以及返回宽元组或布尔值,从接口的角度来看是相同的缺陷:函数在做多件事,或者其返回结果含义模糊。即使函数体很短,也要指出这一点。

  5. 在建议拆分时保持行为不变。 提取必须保持执行顺序、短路求值、错误传播、变量可见性以及任何副作用的时机。如果分解改变了锁释放或写操作的时机,那就是重写而非提取。

修复

  • 小规模、保持行为的提取:立即执行。 将嵌套块提取为命名辅助函数,用卫语句和提前返回替换深层 if 金字塔,将混杂的低层计算提升到名称之后,根据注释中已描述的两个步骤拆分一个函数。这些都不会改变可观察行为。
  • 结构性修改:先确认。 更改签名、移动所有权、合并或重新拆分模块、或用类型替换状态机会改变调用方。先展示修改前后的形态。
  • 保持行为,除非行为本身是错误。 保持执行顺序、短路求值、错误路径和变量修改时机。不要分解你未被要求修改的函数。

报告

以发现项开头,按严重程度从高到低排列:

函数有效行数深度分支路径评估
loadAll()210521拆分:四个阶段,每个阶段已经是注释
applyRules()68414先加卫语句,再拆分两遍处理
parseTable()9513较大但扁平;保留
run()2439短且密集:提取重试循环

然后,针对每个发现:函数体做了什么、你会提取哪些步骤并给出命名、以及拆分带来的代价:间接性、状态移动、调用点变更。

最后以四个分类结束:

  • 已分解:已完成、保持行为的拆分,说明哪些代码移动到了何处。
  • 已提议:值得提取但未经询问不安全,按影响程度排序。
  • 较大但扁平:超过大小阈值但保持完整,说明原因。
  • 非发现项:自动生成的代码,或类似表格的分支体。

短函数不一定是好函数,长而扁平的函数也不一定是坏函数。 分支数、深度和混杂的抽象层次才是缺陷;长度只是通常为之付出的代价。三层嵌套是容忍线,而非法律,其存在是为了在深度增加时重新考虑步骤。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相关技能