Community程式設計與開發github.com

find-complex-functions

找出那些承擔過多職責、難以追蹤的函式:過長的函式主體、深層巢狀條件、混合抽象層級的語句,或難以追蹤的區域變數。

find-complex-functions 是什麼?

這個技能會掃描程式碼,找出那些對開發者來說難以一步掌握、需要耗費更多心力才能理解的函式。它不只看行數,而是深入分析函式的責任數量、巢狀深度、分支路徑數、區域變數數量以及抽象層級的混合程度,從根本上找出複雜度的來源。對於每個被標記的函式,它會建議具體的重構步驟,例如提取輔助函式、採用保護子句與提前返回、改用扁平化資料結構,或引入現有函式庫,並明確指出提取後對行為的影響。此技能適用於任何需要整潔程式碼的平台(如 Claude Code、Cursor、GitHub Copilot),尤其適合在程式碼審查、重構規劃、技術債評估或準備新增功能前使用,確保程式碼庫的長期可維護性。

相容平台~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 行就停止閱讀而遺漏的錯誤。

這裡的發現不是「函式太長」。對於每個發現,描述該函式主體做了什麼、有多少件事、你會提取哪些步驟,或者給出明確的理由說明為什麼當前的形狀是合適的。 一個實作單一連貫演算法的長函式可以是正確的。

流程

  1. 測量主體,然後閱讀它。 記錄實體行數、有效行數(排除空白與註解)、最長巢狀深度,以及區域變數數量。對於手動維護的程式碼,門檻值如下:

    函式大小閱讀難度
    20 行以下理想:主體像一個步驟
    20 到 50 行正常範圍
    50 到 80 行審查:說明各部分是否可以分離
    超過 80 行通常預期要拆分
    超過 200 行高優先級複雜度發現
  2. 計算行數背後代表的真正問題。 對於每個被標記的函式:

    • 責任。 如果誠實的描述需要「並且」,那它就是兩個函式。更強的訊號是兩個不同的呼叫者、操作者或驅動它的原因,這正是分隔的界線。
    • 分支路徑。 計算 if、迴圈、match 分支和 catch。少量是沒問題的;跨巢狀分支相乘的路徑才是訊號,而這正是讓一個短函式變難的原因。
    • 巢狀深度。 深度會降低可接受的長度:隨著複雜度和縮排增加,上限會下降。三層是常見的容忍限度;超過這個深度,應該重構而非繼續新增。同樣的 60 行在深度 1 時沒問題,但在深度 4 時就錯了。
    • 區域變數。 超過大約七到十個時,閱讀者就無法全部記住;這本身就是一個發現。
    • 抽象層級。 在一個函式主體中混合高層級策略與低層級解析、索引或指標運算,無論長度如何都是一個缺陷。 在這些計數遺漏的地方,行數仍然重要:一個巢狀的呼叫鏈可能只是一個陳述式、零個分支,卻有必須按順序閱讀的十六行。
  3. 命名你會提取的步驟,以及適合的技術。 四種技術承擔了大部分的工作:

    • 提取:將巢狀區塊移到一個只關心單一職責的命名輔助函式中。
    • 保護子句與提前返回:先拒絕無效的輸入,讓函式主體在單一縮排層級中執行,而不是包在三層條件式內。
    • 更扁平的資料結構:用對索引、映射(map)或預先建好的清單的一次遍歷,取代巢狀遍歷。
    • 引入函式庫:當巢狀結構源自手動實作的演算法(排序、分組、比對)時,刪除的程式碼就是最大的贏家。 對於鏈式呼叫(如 Promise、Observable 和管道)而不是迴圈,規則相同:將它們組合起來,永遠不要將一個訂閱或管道巢狀在另一個裡面。 然後說明每個輔助函式應該叫什麼名字以及它應該負責什麼。「重構這個函式」不是一個有效的發現,僅僅將行數移到名稱後面也不是。如果提取出來的步驟仍然需要整個函式主體的上下文,那它就不是一個步驟。
  4. 檢查參數列表和回傳形狀。 參數數量過多以及回傳一個龐大的元組或 bool 值,都是從介面端顯現的相同缺陷:該函式正在執行多項工作,或者其結果含糊不清。即使函式主體很短,也應該指出這點。

  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.

相關技能